diff options
Diffstat (limited to 'PhysX_3.4/Documentation/PhysXGuide/Manual')
33 files changed, 15368 insertions, 0 deletions
diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/API.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/API.html new file mode 100644 index 00000000..bf1860a7 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/API.html @@ -0,0 +1,274 @@ +<!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>The PhysX API — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Startup and Shutdown" href="Startup.html" /> + <link rel="prev" title="Building with PhysX" href="BuildingWithPhysX.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Startup.html" title="Startup and Shutdown" + accesskey="N">next</a></li> + <li class="right" > + <a href="BuildingWithPhysX.html" title="Building with PhysX" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="the-physx-api"> +<span id="api"></span><h1>The PhysX API<a class="headerlink" href="#the-physx-api" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This chapter covers the basic patterns common to the PhysX application programming interface (API.) We are committed to keeping this API stable and backwards-compatible from one minor release to the next, to protect the investment you make in your integration code.</p> +<p>The PhysX API is composed primarily of abstract interface classes. Classes, enumerations and functions defined by the API have the prefix Px.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">There is currently one section of the public API which does not have the Px prefix: the PhysX Visual Debugger connection library which has the prefix Pvd.</p> +</div> +<p>The PhysX libraries also expose some classes and functions that are not part of the public API. These are primarily containers and platform abstractions that are required to build the PhysX libraries which are distributed as source, and are also used in the samples. They can be recognized because they do not have the Px prefix. Even though they are in principle accessible to users, they are largely undocumented and we do not maintain compatibility of this code between PhysX versions. For that reason we recommend strongly against their use in applications.</p> +</div> +<div class="section" id="memory-management"> +<span id="memorymanagement"></span><h2>Memory Management<a class="headerlink" href="#memory-management" title="Permalink to this headline">¶</a></h2> +<p>PhysX performs all allocations via the <em>PxAllocatorCallback</em> interface. You must implement this interface in order to initialize PhysX:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">PxAllocatorCallback</span> +<span class="p">{</span> +<span class="nl">public:</span> + <span class="k">virtual</span> <span class="o">~</span><span class="n">PxAllocatorCallback</span><span class="p">()</span> <span class="p">{}</span> + <span class="k">virtual</span> <span class="kt">void</span><span class="o">*</span> <span class="n">allocate</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">typeName</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">filename</span><span class="p">,</span> + <span class="kt">int</span> <span class="n">line</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">deallocate</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span> <span class="n">ptr</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The size of the request is specified in bytes, and PhysX requires that the memory that is returned be 16-byte aligned. On many platforms malloc() returns memory that is 16-byte aligned, and on Windows the system function _aligned_malloc() provides this capability. The other parameters to allocate() are a string which identifies the type of allocation, and the __FILE__ and __LINE__ location inside PhysX code where the allocation was made. Refer to PxAllocatorCallback::allocate() to find out more about them.</p> +<p>A simple implementation of the allocator callback class can be found in the PhysX Extensions library, see class <em>PxDefaultAllocatorCallback</em>.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">On some platforms PhysX uses system library calls to determine the correct type name, and the system function that returns the type name may call the system memory allocator. If you are instrumenting system memory allocations, you may observe this behavior. To prevent PhysX requesting type names, disable allocation names using the method PxFoundation::setReportAllocationNames().</p> +</div> +<p>You can place PhysX objects in memory owned by the application using PhysX' binary deserialization mechanism. See <a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a> for details.</p> +<p>As an alternative to instrumenting the allocator, you can obtain detailed information about memory allocation in the PhysX Visual Debugger (see: <a class="reference internal" href="VisualDebugger.html#physxvisualdebugger"><em>PhysX Visual Debugger (PVD)</em></a>)</p> +</div> +<div class="section" id="error-reporting"> +<span id="errorreporting"></span><h2>Error Reporting<a class="headerlink" href="#error-reporting" title="Permalink to this headline">¶</a></h2> +<p>PhysX logs all error messages through the <em>PxErrorCallback</em> interface. You must implement this interface in order to initialize PhysX:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">UserErrorCallback</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxErrorCallback</span> +<span class="p">{</span> +<span class="nl">public:</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">reportError</span><span class="p">(</span><span class="n">PxErrorCode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">code</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">message</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">file</span><span class="p">,</span> + <span class="kt">int</span> <span class="n">line</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// error processing implementation</span> + <span class="p">...</span> + <span class="p">}</span> +<span class="p">};</span> +</pre></div> +</div> +<p>There is only a single function to implement, <em>reportError</em>. This function should log the passed message, or print it on the application's output console. For the more serious error codes <em>eABORT</em>, <em>eINVALID_PARAMETER</em>, <em>eINVALID_OPERATION</em>, <em>eINTERNAL_ERROR</em> and <em>eOUT_OF_MEMORY</em>, breaking into the debugger may be a more appropriate choice. Whatever you do, do not just ignore the messages.</p> +<p>A simple implementation of the error callback class can be found in the PhysX Extensions library, see class <em>PxDefaultErrorCallback</em>.</p> +</div> +<div class="section" id="math-classes"> +<span id="mathtypes"></span><h2>Math Classes<a class="headerlink" href="#math-classes" title="Permalink to this headline">¶</a></h2> +<p>The common math classes used in PhysX are PxVec2, PxVec3, PxVec4, PxMat33, PxMat44, PxTransform, PxPlane and PxQuat, which are are defined in their respective header files, e.g. (SDKRoot)/Include/foundation/PxVec3.h. The types support standard operator overloads and typical math operations. Zero and identity objects where appropriate can be constructed by passing the arguments PxZero and PxIdentity respectively.</p> +<p>Some points to note are:</p> +<ul class="simple"> +<li>PxTransform is a representation of a rigid body transform as a rotation quaternion and a position vector, and PhysX functions which take transforms all use this type.</li> +<li>PxPlane is a homogeneous plane equation: that is, the constructor PxPlane(n, d) represents the equation n.x + d = 0.</li> +</ul> +<p>PxMat33 and PxMat44 matrices represent transformations with basis vectors in the columns (pre-multiply with matrix on the left hand side) and are stored in column-major order. This format is layout compatible with popular graphics APIs such as OpenGL and Direct3D. For example, to set the model transformation for a rigid body in OpenGL:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// retrieve world space transform of rigid body</span> +<span class="n">PxTransform</span> <span class="n">t</span> <span class="o">=</span> <span class="n">rigidActor</span><span class="p">.</span><span class="n">getGlobalPose</span><span class="p">();</span> + +<span class="c1">// convert to matrix form</span> +<span class="n">PxMat44</span> <span class="n">m</span> <span class="o">=</span> <span class="n">PxMat44</span><span class="p">(</span><span class="n">t</span><span class="p">);</span> + +<span class="c1">// set to OpenGL</span> +<span class="n">glMatrixMode</span><span class="p">(</span><span class="n">GL_MODELVIEW</span><span class="p">);</span> +<span class="n">glPushMatrix</span><span class="p">();</span> + +<span class="c1">// PxMat44::front() returns a pointer to the first matrix element</span> +<span class="n">glMultMatrixf</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">front</span><span class="p">());</span> + +<span class="c1">// draw model</span> + +<span class="n">glPopMatrix</span><span class="p">()</span> +</pre></div> +</div> +<p>DirectX uses row-major storage for matrices by default (D3DMATRIX), but also stores basis vectors in rows (post-multiply on the right), so PxMat44 may be used in place of D3DXMATRIX types directly.</p> +</div> +<div class="section" id="connecting-physx-objects-with-user-application-objects"> +<span id="userdata"></span><h2>Connecting PhysX Objects with User Application Objects<a class="headerlink" href="#connecting-physx-objects-with-user-application-objects" title="Permalink to this headline">¶</a></h2> +<p>Often an application needs to associate PhysX objects with application objects for game logic or rendering purposes. An easy way to connect a single user application object with a PhysX object is to use the <em>userData</em> member provided by the most important PhysX classes (<em>PxActor::userData</em>, <em>PxShape::userData</em>, <em>PxMaterial::userData</em>, ...). The <em>userData</em> member is a <em>void*</em> pointer which is reserved for application use. Each class only has one <em>userData</em> field, so to manage multiple associations another mechanism must be used.</p> +</div> +<div class="section" id="type-casting"> +<h2>Type Casting<a class="headerlink" href="#type-casting" title="Permalink to this headline">¶</a></h2> +<p>PhysX API interface classes inherit from a top-level interface called PxBase, which provides mechanisms for type-safe down-casting between interface types. For example, to cast from a PxActor to a PxRigidDynamic, use the following idiom:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxActor</span><span class="o">*</span> <span class="n">actor</span> <span class="o">=</span> <span class="o"><</span><span class="p">...</span><span class="o">></span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">myActor</span> <span class="o">=</span> <span class="n">actor</span><span class="o">-></span><span class="n">is</span><span class="o"><</span><span class="n">PxRigidDynamic</span><span class="o">></span><span class="p">();</span> + +<span class="k">const</span> <span class="n">PxActor</span><span class="o">*</span> <span class="n">actor</span> <span class="o">=</span> <span class="o"><</span><span class="p">...</span><span class="o">></span> +<span class="k">const</span> <span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">myActor</span> <span class="o">=</span> <span class="n">actor</span><span class="o">-></span><span class="n">is</span><span class="o"><</span><span class="n">PxRigidDynamic</span><span class="o">></span><span class="p">();</span> +</pre></div> +</div> +<p>This pattern can be used to cast to intermediate types in the hierarchy such as PxRigidActor, but this is somewhat slower than casting to concrete types. In addition, PxBase provides the following capabilities:</p> +<ul class="simple"> +<li>getConcreteType() provides an integer value which corresponds to the concrete type of an object</li> +<li>getConcreteTypeName() provides a string name of the concrete type</li> +<li>isKindOf() provides string-based testing of inheritance</li> +</ul> +</div> +<div class="section" id="reference-counting"> +<span id="basicreferencecounting"></span><h2>Reference Counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h2> +<p>Some PhysX objects are designed to be shared and referenced multiple times in a PhysX scene graph. For example, a PxConvexMesh may be referenced by multiple PxShape objects, each sharing the same geometry but associated with different actors. The specific types are PxTriangleMesh, PxHeightField, PxConvexMesh, PxMaterial, PxClothFabric, and PxShape. Each object of these types has a reference count. The rules for reference counting are as follows:</p> +<ul class="simple"> +<li>when an object is created from PxPhysics, it has a reference count of 1.</li> +<li>when an object's reference count reaches 0, the object is destroyed.</li> +<li>when a new counted reference is created, the reference count is incremented. Counted references are as follows:<ul> +<li>when a PxShape references a PxConvexMesh, PxHeightfield, or PxTriangleMesh.</li> +<li>when a PxShape references a PxMaterial.</li> +<li>when a PxRigidActor references a PxShape.</li> +<li>when a PxCloth references a PxClothFabric.</li> +</ul> +</li> +<li>when a counted reference is destroyed, or the object's release() method is called, the reference count is decremented.</li> +<li>when an object is created through deserialization, its reference count is 1, plus the number of counted references that exist to the object.</li> +</ul> +<p>The initial reference count of 1 ensures the object is not destroyed until the application allows it by calling release() - thereafter it will be destroyed when no remaining counted references to it exist.</p> +<p>For example, if you create a shape using PxPhysics::createShape() and attach it to an actor with PxRigidActor::attachShape(), it has a reference count of 2. If you then call the shape's +release() method, it has a reference count of 1. When the actor is destroyed, or the shape is detached from the actor, the reference count is decremented, and since it is now 0, the shape is destroyed.</p> +<p>The acquireReference() method increments the reference count of an object. For example, when a spatial query returns a reference to a mesh shape, and you want to pass that result to another thread for deferred processing, incrementing the reference count will ensure that even if the shape referencing the mesh is released, the mesh continues to exist.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">subtypes of PxGeometry do not have counted references to the meshes to which they point, e.g. when PxConvexMeshGeometry points to a PxConvexMesh. A counted reference exists only when the geometry is within a PxShape.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">shapes are often created using the utility method PxRigidActorExt::createExclusiveShape(). Take special care when deserializing such actors (see <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollisionshapes"><em>Shapes</em></a> and <a class="reference internal" href="Serialization.html#deserializereferencecounting"><em>Reference Counting of Deserialized Objects</em></a>)</p> +</div> +</div> +<div class="section" id="using-different-units"> +<span id="pxtolerancescale"></span><h2>Using Different Units<a class="headerlink" href="#using-different-units" title="Permalink to this headline">¶</a></h2> +<p>PhysX is designed to produce correct results regardless of the units of length or mass, so long as inputs use those units consistently. However, there are certain tolerances values whose defaults need to be adjusted depending on the units. In order to ensure that these tolerances default to reasonable values, adjust the values in PxTolerancesScale when creating the PxPhysics and PxCooking interfaces. Tolerances for objects are set at creation time, and may then be overridden by the application.</p> +<p>You should set tolerances based on the typical size of objects in your simulation. For example, if you are working with objects of size approximately one meter, but in units of centimeters, you should set the scale as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxFoundation</span><span class="o">*</span> <span class="n">foundation</span> <span class="o">=</span> <span class="p">...;</span> +<span class="n">PxTolerancesScale</span> <span class="n">scale</span><span class="p">;</span> +<span class="n">scale</span><span class="p">.</span><span class="n">length</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> <span class="c1">// typical length of an object</span> +<span class="n">scale</span><span class="p">.</span><span class="n">speed</span> <span class="o">=</span> <span class="mi">981</span><span class="p">;</span> <span class="c1">// typical speed of an object, gravity*1s is a reasonable choice</span> +<span class="n">PxPhysics</span> <span class="o">*</span><span class="n">p</span> <span class="o">=</span> <span class="n">PxCreatePhysics</span><span class="p">(</span><span class="n">PX_PHYSICS_VERSION</span><span class="p">,</span> <span class="o">*</span><span class="n">foundation</span><span class="p">,</span> <span class="n">scale</span><span class="p">,</span> <span class="p">...);</span> +</pre></div> +</div> +<p>This will result in the defaults for values like PxShape::contactDistance being scaled appropriately for your objects.</p> +<p>You can also set the typical object mass in PxTolerancesScale.</p> +<p>It is important to use the same PxTolerances value for initialization of PxCooking and PxPhysics, and also when creating PxSceneDesc objects.</p> +</div> +<div class="section" id="assertions"> +<span id="id1"></span><h2>Assertions<a class="headerlink" href="#assertions" title="Permalink to this headline">¶</a></h2> +<p>PhysX uses the PX_DEBUG macro to enable or disable assertions. This macro is not set in the PhysXCore and PhysXCommon libraries, and so by default these libraries will not trigger assertions, however you may configure the libraries provided as source to enable them. When an assert is triggered, PhysX calls an assert handler. By default the assert handler will trigger a debug breakpoint. However, you may call the function PxSetAssertHandler() to customize the assert handler.</p> +</div> +<div class="section" id="determinism"> +<h2>Determinism<a class="headerlink" href="#determinism" title="Permalink to this headline">¶</a></h2> +<p>PhysX is deterministic in the sense it will produce identical simulation results from the same sequence of API calls applied from the point where a scene is originally created (and the same responses from simulation callbacks which modify data). Note that removing all the objects from a scene is not in general sufficient to reinitialize it for this purpose.</p> +<p>PhysX simulation behavior is not sensitive to the number of CPU worker threads used.</p> +<p>An important caveat to determinism is the state of the x87 FPU on 32-bit Intel/AMD platforms. Some compilers produce x87 floating point instructions even when configured to prefer SSE instructions, and the results of those operations may depend on the state of the x87 control word. Since it is too expensive to modify the x87 FPU state at every PhysX entry point, this is delegated to the application if necessary. PhysX operations do not result in changes to the x87 control word, but certain other libraries (including DirectX) may modify it.</p> +<p>Configurations in which this is known to be a issue are all 32-bit MSVC debug configurations, and all MSVC 32-bit checked, release and profile configurations prior to Visual Studio 2012.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">The PhysX API</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#memory-management">Memory Management</a></li> +<li><a class="reference internal" href="#error-reporting">Error Reporting</a></li> +<li><a class="reference internal" href="#math-classes">Math Classes</a></li> +<li><a class="reference internal" href="#connecting-physx-objects-with-user-application-objects">Connecting PhysX Objects with User Application Objects</a></li> +<li><a class="reference internal" href="#type-casting">Type Casting</a></li> +<li><a class="reference internal" href="#reference-counting">Reference Counting</a></li> +<li><a class="reference internal" href="#using-different-units">Using Different Units</a></li> +<li><a class="reference internal" href="#assertions">Assertions</a></li> +<li><a class="reference internal" href="#determinism">Determinism</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="BuildingWithPhysX.html" + title="previous chapter">Building with PhysX</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Startup.html" + title="next chapter">Startup and Shutdown</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" /> + <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="Startup.html" title="Startup and Shutdown" + >next</a></li> + <li class="right" > + <a href="BuildingWithPhysX.html" title="Building with PhysX" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/AdvancedCollisionDetection.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/AdvancedCollisionDetection.html new file mode 100644 index 00000000..b9a0cf3d --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/AdvancedCollisionDetection.html @@ -0,0 +1,472 @@ +<!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>Advanced Collision Detection — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Joints" href="Joints.html" /> + <link rel="prev" title="Simulation" href="Simulation.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Joints.html" title="Joints" + accesskey="N">next</a></li> + <li class="right" > + <a href="Simulation.html" title="Simulation" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="advanced-collision-detection"> +<span id="advancedcollisiondetection"></span><h1>Advanced Collision Detection<a class="headerlink" href="#advanced-collision-detection" title="Permalink to this headline">¶</a></h1> +<div class="section" id="tuning-shape-collision-behavior"> +<span id="shapecollisiontuning"></span><h2>Tuning Shape Collision Behavior<a class="headerlink" href="#tuning-shape-collision-behavior" title="Permalink to this headline">¶</a></h2> +<p>Shapes used for contact generation influence the motion of the dynamic rigid bodies they are attached to through contact points. The constraint solver generates impulsive forces at the contact points to keep the shapes resting or moving without passing through each other. Shapes have two important parameters that control how collision detection generates contact points between them, which in turn are central for their behavior when colliding or stacking: contactOffset and restOffset. They are set using PxShape::setContactOffset() and PxShape::setRestOffset() respectively. Neither of these values is used directly. Collision detection always operates on a pair of potentially colliding shapes, and it always considers the sum of the offsets of the two shapes. We call these the contactDistance and restDistance respectively.</p> +<p>Collision detection is able to generate contact points between two shapes when they are still a distance apart, when they are exactly touching, or when they are inter-penetrating. To make the discussion simpler, we treat interpenetration as a negative distance. So the distance between two shapes can be positive, zero, or negative. SeparationDistance is the distance at which collision detection will start to generate contacts. It has to be greater than zero, meaning that PhysX will always generate contacts when two shapes are penetrating (unless collision detection between the two shapes is in some way completely disabled, such as with filtering). By default, when using metric units and default scaling in PxTolerancesScale, contactOffset is 0.02, which means contactDistance will work out to 4 centimeters. So when two shapes approach each other within 4 centimeters, contacts will be generated until they are again moved further apart than 4 centimeters.</p> +<p>The generation of contact points does not however mean that a large impulse will immediately be applied at these locations to separate the shapes, or to even prevent further motion in the direction of penetration. This would make the simulation jitter unless the simulation time step is selected to be tiny, which is not desirable for real time performance. Instead, we want the force at the contact to smoothly increase as penetration increases until it reaches a value sufficiently high to stop any further penetrating motion. The distance at which this maximum force is reached is the restDistance, because at this distance two shapes stacked on each other will reach static equilibrium and come to rest. When the shapes are for some reason pushed together so much that they have a distance below restDistacnce, an even greater force is applied to push them apart until they are at restDistance again. The variation of force applied as the distance changes is not necessarily linear, but it is smooth and continuous which results in a pleasing simulation even at large time steps.</p> +<p>There are a few different things to consider when choosing contactOffset and restOffset for shapes. Typically the same values can be used for all shapes in a simulation. It makes sense to determine restOffset first. The goal is typically to have the graphics shapes appear to stack such that they are exactly touching, like bodies do in real life. If the collision shapes are sized to be the exact same size as the graphics shapes, a restOffset of zero is needed. If the collision shapes are an epsilon bigger than the graphics shapes, a restOffset of negative epsilon is correct. This will let the larger collision shapes sink into each other until the smaller graphics shapes touch too. restOffsets that are larger than zero are practical for example if there are problems with sliding on triangle geometry where the penetration based contact generation has more trouble producing smooth contact points than a separation one, resulting in a smoother slide.</p> +<p>Once the restOffset is determined, the contactOffset should be chosen to be a value a slightly larger. The rule of thumb is to make the difference between the two as small as possible that still effectively avoids jitter at the time step size the simulation uses. A larger time step will need the difference to be larger. The drawback of setting it too large is that contacts will be generated sooner as two shapes approach, which drives up the total number of contacts that the simulation has to worry about. This will decrease in performance. Also, the simulation code often makes the assumption that contact points are close to the convex shapes' surface. If the contact offset is very large this assumption breaks down which could lead to behavior artefacts.</p> +</div> +<div class="section" id="contact-modification"> +<span id="id1"></span><h2>Contact Modification<a class="headerlink" href="#contact-modification" title="Permalink to this headline">¶</a></h2> +<p>Under certain circumstances, it may be necessary to specialize contact behavior. For example to implement sticky contacts, give objects the appearance of floating or swimming inside each other, or making objects go through apparent holes in walls. A simple approach to achieve such effects is to let the user change the properties of contacts after they have been generated by collision detection, but before the contact solver. Because both of these steps occur within the scene simulate() function, a callback must be used.</p> +<p>The callback occurs for all pairs of colliding shapes for which the user has specified the pair flag PxPairFlag::eMODIFY_CONTACTS in the filter shader.</p> +<p>To listen to these modify callbacks, derive from the class PxContactModifyCallback:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyContactModification</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxContactModifyCallback</span> +<span class="p">{</span> + <span class="p">...</span> + <span class="kt">void</span> <span class="n">onContactModify</span><span class="p">(</span><span class="n">PxContactModifyPair</span><span class="o">*</span> <span class="k">const</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">);</span> +<span class="p">};</span> +</pre></div> +</div> +<p>And then implement the function onContactModify of PxContactModifyCallback:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">MyContactModification</span><span class="o">::</span><span class="n">onContactModify</span><span class="p">(</span><span class="n">PxContactModifyPair</span> <span class="o">*</span><span class="k">const</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">count</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="p">...</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Every pair of shapes comes with an array of contact points, that have a number of properties that can be modified, such as position, contact normal, and separation. For the time being, restitution and friction properties of the contacts cannot be modified. See PxModifiableContact and PxContactSet for properties that can be modified.</p> +<dl class="docutils"> +<dt>In addition to modifying contact properties, it is possible to:</dt> +<dd><ul class="first last simple"> +<li>Set target velocities for each contact</li> +<li>Limit the maximum impulse applied at each contact</li> +<li>Adjust inverse mass and inverse inertia scales separately for each body</li> +</ul> +</dd> +</dl> +<p>Conveyor belt-like effects can be achieved by setting target velocities. Best results are achieved by having target velocities running in tangential directions to the contact normal but the solver does also support target velocities in the direction of the contact normal.</p> +<p>The user can limit the impulse applied at each contact by limiting the maximum impulse applied at each contact. This can be useful to produce "soft" contact effects, e.g. to give the impression of energy dissipation due to compression or to limit the impulse applied on a dynamic body due to a kinematic collision. Note that limiting the maximum impulse can potentially lead to additional penetration and bodies passing through each-other.</p> +<p>Adjusting mass and inertia scales can be used to tune how contacts between a pair of bodies affect the bodies' linear and angular velocities respectively. Each body in the contact pair has a separate inverse mass and inverse inertia scale. These scales are initialized to 1 and can be adjusted as part of the callback. Note that these values perform local mass modification within the contact pair and affect all contacts within the pair.</p> +<p>Uniformly scaling a body's inverse mass and inverse inertia by the same value results in the body behaving like a body that is either heavier or lighter depending on the values used. Providing inverse mass/inverse inertia scales < 1 results in the body appearing heavier; providing scales > 1 result in the body appearing lighter. For example, inverse mass/inertia scales of 0.5 result in the body appearing to have double the mass. Providing inverse mass/inertia scales of 4 would result in the body appearing to have a quarter of its original mass. Providing inverse mass/inertia scale of 0 results in the body behaving as if it has infinite mass.</p> +<p>However, it is also possible to non-uniform scale a body's inverse mass and inverse inertia by providing different values to a body's inverse mass and inverse inertia scale. For example, it is possible to reduce or increase the amount of angular velocity change as a result of contacts by adjusting just the inverse inertia scale. The use-cases for this kind of modification are extremely game-dependent but may involve, for example, tuning interactions between a player's vehicle and traffic vehicles in an arcade-style driving game, where the player's car is expected to be bumped by traffic vehicles but where it would be extremely frustrating to the player if the car was to spin-out as a result of the collision. This could also be achieved by making the traffic vehicles much lighter than the player's vehicle but this may make the traffic vehicles appear "too light" and therefore damage the player's immersion.</p> +<p>When performing local mass modification, the impulse reported in PxSimulationEventCallback::onContact() will be relative to the locally scaled masses of the bodies involved in that contact. Therefore, this reported impulse may no longer accurately reflect the change in momentum caused by a given contact. In order to resolve this issue, we have provided the following methods in the rigid body extensions to extract the linear and angular impulse and velocity change caused by a contact using local mass modification:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">computeLinearAngularImpulse</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">globalPose</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">point</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">impulse</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invMassScale</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invInertiaScale</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">linearImpulse</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">angularImpulse</span><span class="p">);</span> + +<span class="k">static</span> <span class="kt">void</span> <span class="nf">computeVelocityDeltaFromImpulse</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">globalPose</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">point</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">impulse</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invMassScale</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">invInertiaScale</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">deltaLinearVelocity</span><span class="p">,</span> + <span class="n">PxVec3</span><span class="o">&</span> <span class="n">deltaAngularVelocity</span><span class="p">);</span> +</pre></div> +</div> +<p>These methods return separate linear and angular impulse and velocity change values to reflect the fact that the mass and inertia may have been non-uniformly scaled. When local mass modification has been used, it may be necessary to extract separate linear and angular impulses for each contact point, for each body in the pair. Please note that these helper functions are provided to provide users with accurate impulse values and are by no means mandatory. For simple use-cases, e.g. triggering effects or damage based on impulse thresholds, the single impulse value reported by the contact report should be perfectly acceptable even when local mass modification has been used. However, if local mass modification has been used and the impulse values are being used for more complex behaviors, e.g. balance control for a ragdoll, then these helper functions will most-likely be required to achieve correct behavior. Please note that, in the case of articulations, computeLinearAngularImpulse will return the correct impulse applied on respective articulation link. However, computeVelocityDeltaFromImpulse will not return the correct velocity changes for an articulation link because it does not take the effect of any other links of the articulation into account.</p> +<dl class="docutils"> +<dt>In addition, the following considerations must be made when using local mass modification:</dt> +<dd><ul class="first last simple"> +<li>Force thresholding for callbacks will be based on the scalar impulse value in contact reports. This was calculated using the scaled mass/inertias of the bodies so using mass scaling may require these thresholds to be re-tuned.</li> +<li>Maximum impulse clamping occurs in the solver on an impulse value operating on the scaled masses/inertias. As a result, the magnitude of applied impulses calculated from computeLinearAngularImpulse(...) may exceed the maxImpulse in situations where mass scaling was used. In situations where uniform mass scaling was used, the magnitude of the magnitude of linear impulse will not exceed massScale * maxImpulse and angular impulse will not exceed inertiaScale * maxImpulse.</li> +</ul> +</dd> +</dl> +<p>There are a couple of special requirements for the callback due to the fact that it is coming from deep inside the SDK. In particular, the callback should be thread safe and reentrant. In other words, the SDK may call onContactModify() from any thread and it may be called concurrently (i.e., asked to process sets of contact modification pairs simultaneously).</p> +<p>The contact modification callback can be set using the contactModifyCallback member of PxSceneDesc or the setContactModifyCallback() method of PxScene.</p> +</div> +<div class="section" id="contact-reporting"> +<h2>Contact reporting<a class="headerlink" href="#contact-reporting" title="Permalink to this headline">¶</a></h2> +<p>Here is an example for a contact event function from SampleSubmarine:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">SampleSubmarine</span><span class="o">::</span><span class="n">onContact</span><span class="p">(</span><span class="k">const</span> <span class="n">PxContactPairHeader</span><span class="o">&</span> <span class="n">pairHeader</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">*</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">nbPairs</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">nbPairs</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">&</span> <span class="n">cp</span> <span class="o">=</span> <span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> + + <span class="k">if</span><span class="p">(</span><span class="n">cp</span><span class="p">.</span><span class="n">events</span> <span class="o">&</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eNOTIFY_TOUCH_FOUND</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">if</span><span class="p">((</span><span class="n">pairHeader</span><span class="p">.</span><span class="n">actors</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="n">mSubmarineActor</span><span class="p">)</span> <span class="o">||</span> + <span class="p">(</span><span class="n">pairHeader</span><span class="p">.</span><span class="n">actors</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="n">mSubmarineActor</span><span class="p">))</span> + <span class="p">{</span> + <span class="n">PxActor</span><span class="o">*</span> <span class="n">otherActor</span> <span class="o">=</span> <span class="p">(</span><span class="n">mSubmarineActor</span> <span class="o">==</span> <span class="n">pairHeader</span><span class="p">.</span><span class="n">actors</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span> <span class="o">?</span> + <span class="n">pairHeader</span><span class="p">.</span><span class="n">actors</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">:</span> <span class="n">pairHeader</span><span class="p">.</span><span class="n">actors</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> + <span class="n">Seamine</span><span class="o">*</span> <span class="n">mine</span> <span class="o">=</span> <span class="k">reinterpret_cast</span><span class="o"><</span><span class="n">Seamine</span><span class="o">*></span><span class="p">(</span><span class="n">otherActor</span><span class="o">-></span><span class="n">userData</span><span class="p">);</span> + <span class="c1">// insert only once</span> + <span class="k">if</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">find</span><span class="p">(</span><span class="n">mMinesToExplode</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">mMinesToExplode</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">mine</span><span class="p">)</span> <span class="o">==</span> + <span class="n">mMinesToExplode</span><span class="p">.</span><span class="n">end</span><span class="p">())</span> + <span class="n">mMinesToExplode</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">mine</span><span class="p">);</span> + + <span class="k">break</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>SampleSubmarine is a subclass of PxSimulationEventCallback. onContact receives the pair for which the requested contact events have been triggered. The above function is only interested in eNOTIFY_TOUCH_FOUND events, which are raised whenever two shapes start to touch. In fact it is only interested in touch events of the submarine -- which is checked in the second if-statement. It then goes on to assume that the second actor is a mine (which works in this example because the sample is configured such that no other contact reports will get sent when a submarine actor is involved). After that, it adds the mine to a set of mines that should explode during the next update.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">By default collisions between kinematic rigid bodies and kinematic and static rigid bodies will not get reported. To enable these reports raise the PxSceneFlag::eENABLE_KINEMATIC_PAIRS or ::eENABLE_KINEMATIC_STATIC_PAIRS flag respectively by calling PxScene::setFlag().</p> +</div> +<p>Frequently, users are only interested in contact reports, if the force of impact is larger than a certain threshold. This allows to reduce the amount of reported pairs which need to get processed. To take advantage of this option the following additional configurations are necessary:</p> +<blockquote> +<div><ul class="simple"> +<li>Use PxPairFlag::eNOTIFY_THRESHOLD_FORCE_FOUND, ::eNOTIFY_THRESHOLD_FORCE_PERSISTS, ::eNOTIFY_THRESHOLD_FORCE_LOST instead of ::eNOTIFY_TOUCH_FOUND etc.</li> +<li>Specify the threshold force for a dynamic rigid body through PxRigidDynamic::setContactReportThreshold(). If the body collides with an other object and the contact force is above the threshold, a report will get sent (if enabled according to the PxPairFlag setting of the pair). If two colliding dynamic bodies both have a force threshold specified then the lower threshold will be used.</li> +</ul> +</div></blockquote> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">If a dynamic rigid body collides with multiple static objects, then the impact force of all those contacts will get summed up and used to compare against the force threshold. In other words, even if the impact force against each individual static object is below the threshold, the contact reports will still get sent for each pair if the sum of those forces exceeds the threshold.</p> +</div> +<div class="section" id="contact-reports-and-ccd"> +<h3>Contact Reports and CCD<a class="headerlink" href="#contact-reports-and-ccd" title="Permalink to this headline">¶</a></h3> +<p>If continuous collision detection (CCD) with multiple passes is enabled, then a fast moving object might bounce on and off the same object multiple times during a single simulation step. By default, only the first impact will get reported as a <em>eNOTIFY_TOUCH_FOUND</em> event in this case. To get events for the other impacts too, the <em>PxPairFlag</em> <em>eNOTIFY_TOUCH_CCD</em> has to be raised for the collision pair. This will trigger <em>eNOTIFY_TOUCH_CCD</em> events for the non primary impacts. For performance reasons, the system can not always tell whether the contact pair lost touch in one of the previous CCD passes and thus can also not always tell whether the contact is new or has persisted. <em>eNOTIFY_TOUCH_CCD</em> just reports when the two collision objects were detected as being in contact during a CCD pass.</p> +</div> +</div> +<div class="section" id="extracting-contact-information"> +<h2>Extracting Contact information<a class="headerlink" href="#extracting-contact-information" title="Permalink to this headline">¶</a></h2> +<p>The onContact simulation event permits read-only access to all contact points for a given PxContactPair. In previous releases, these were available as a flattened array of PxContactPoint objects. However, PhysX 3.3 introduces a new format for this data: the compressed contact stream. The contact information is now compressed into an appropriate format for a given PxContactPair depending on certain properties, e.g. depending on the shapes involved, the properties of the contacts, materials and whether the contacts are modifiable.</p> +<p>As there are a large number of combinations of different formats, the user is provided with two built-in mechanisms to access the contact data. The first approach provides a mechanism to extract contacts from a user buffer and can be used as below:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">MySimulationCallback</span><span class="o">::</span><span class="n">onContact</span><span class="p">(</span><span class="k">const</span> <span class="n">PxContactPairHeader</span><span class="o">&</span> <span class="n">pairHeader</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">*</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">nbPairs</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">const</span> <span class="n">PxU32</span> <span class="n">bufferSize</span> <span class="o">=</span> <span class="mi">64</span><span class="p">;</span> + <span class="n">PxContactPairPoint</span> <span class="n">contacts</span><span class="p">[</span><span class="n">bufferSize</span><span class="p">];</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">nbPairs</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">&</span> <span class="n">cp</span> <span class="o">=</span> <span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> + + <span class="n">PxU32</span> <span class="n">nbContacts</span> <span class="o">=</span> <span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">extractContacts</span><span class="p">(</span><span class="n">contacts</span><span class="p">,</span> <span class="n">bufferSize</span><span class="p">);</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">j</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">j</span> <span class="o"><</span> <span class="n">nbContacts</span><span class="p">;</span> <span class="n">j</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">PxVec3</span> <span class="n">point</span> <span class="o">=</span> <span class="n">contacts</span><span class="p">[</span><span class="n">j</span><span class="p">].</span><span class="n">position</span><span class="p">;</span> + <span class="n">PxVec3</span> <span class="n">impulse</span> <span class="o">=</span> <span class="n">contacts</span><span class="p">[</span><span class="n">j</span><span class="p">].</span><span class="n">impulse</span><span class="p">;</span> + <span class="n">PxU32</span> <span class="n">internalFaceIndex0</span> <span class="o">=</span> <span class="n">contacts</span><span class="p">[</span><span class="n">j</span><span class="p">].</span><span class="n">internalFaceIndex0</span><span class="p">;</span> + <span class="n">PxU32</span> <span class="n">internalFaceIndex1</span> <span class="o">=</span> <span class="n">contacts</span><span class="p">[</span><span class="n">j</span><span class="p">].</span><span class="n">internalFaceIndex1</span><span class="p">;</span> + <span class="c1">//...</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This approach requires copying data to a temporary buffer in order to access it. The second approach allows the user to iterate over the contact information without extracting their own copy:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">MySimulationCallback</span><span class="o">::</span><span class="n">onContact</span><span class="p">(</span><span class="k">const</span> <span class="n">PxContactPairHeader</span><span class="o">&</span> <span class="n">pairHeader</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">*</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">nbPairs</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">nbPairs</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">&</span> <span class="n">cp</span> <span class="o">=</span> <span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> + + <span class="n">PxContactStreamIterator</span> <span class="nf">iter</span><span class="p">(</span><span class="n">cp</span><span class="p">.</span><span class="n">contactPatches</span><span class="p">,</span> <span class="n">cp</span><span class="p">.</span><span class="n">contactPoints</span><span class="p">,</span> <span class="n">cp</span><span class="p">.</span><span class="n">getInternalFaceIndices</span><span class="p">(),</span> <span class="n">cp</span><span class="p">.</span><span class="n">patchCount</span><span class="p">,</span> <span class="n">cp</span><span class="p">.</span><span class="n">contactCount</span><span class="p">);</span> + + <span class="k">const</span> <span class="n">PxReal</span><span class="o">*</span> <span class="n">impulses</span> <span class="o">=</span> <span class="n">cp</span><span class="p">.</span><span class="n">contactImpulses</span><span class="p">;</span> + + <span class="n">PxU32</span> <span class="n">flippedContacts</span> <span class="o">=</span> <span class="p">(</span><span class="n">cp</span><span class="p">.</span><span class="n">flags</span> <span class="o">&</span> <span class="n">PxContactPairFlag</span><span class="o">::</span><span class="n">eINTERNAL_CONTACTS_ARE_FLIPPED</span><span class="p">);</span> + <span class="n">PxU32</span> <span class="n">hasImpulses</span> <span class="o">=</span> <span class="p">(</span><span class="n">cp</span><span class="p">.</span><span class="n">flags</span> <span class="o">&</span> <span class="n">PxContactPairFlag</span><span class="o">::</span><span class="n">eINTERNAL_HAS_IMPULSES</span><span class="p">);</span> + <span class="n">PxU32</span> <span class="n">nbContacts</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + + <span class="k">while</span><span class="p">(</span><span class="n">iter</span><span class="p">.</span><span class="n">hasNextPatch</span><span class="p">())</span> + <span class="p">{</span> + <span class="n">iter</span><span class="p">.</span><span class="n">nextPatch</span><span class="p">();</span> + <span class="k">while</span><span class="p">(</span><span class="n">iter</span><span class="p">.</span><span class="n">hasNextContact</span><span class="p">())</span> + <span class="p">{</span> + <span class="n">iter</span><span class="p">.</span><span class="n">nextContact</span><span class="p">();</span> + <span class="n">PxVec3</span> <span class="n">point</span> <span class="o">=</span> <span class="n">iter</span><span class="p">.</span><span class="n">getContactPoint</span><span class="p">();</span> + <span class="n">PxVec3</span> <span class="n">impulse</span> <span class="o">=</span> <span class="n">hasImpulses</span> <span class="o">?</span> <span class="n">dst</span><span class="p">.</span><span class="n">normal</span> <span class="o">*</span> <span class="n">impulses</span><span class="p">[</span><span class="n">nbContacts</span><span class="p">]</span> <span class="o">:</span> <span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span> + + <span class="n">PxU32</span> <span class="n">internalFaceIndex0</span> <span class="o">=</span> <span class="n">flippedContacts</span> <span class="o">?</span> + <span class="n">iter</span><span class="p">.</span><span class="n">getFaceIndex1</span><span class="p">()</span> <span class="o">:</span> <span class="n">iter</span><span class="p">.</span><span class="n">getFaceIndex0</span><span class="p">();</span> + <span class="n">PxU32</span> <span class="n">internalFaceIndex1</span> <span class="o">=</span> <span class="n">flippedContacts</span> <span class="o">?</span> + <span class="n">iter</span><span class="p">.</span><span class="n">getFaceIndex0</span><span class="p">()</span> <span class="o">:</span> <span class="n">iter</span><span class="p">.</span><span class="n">getFaceIndex1</span><span class="p">();</span> + <span class="c1">//...</span> + <span class="n">nbContacts</span><span class="o">++</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This approach is slightly more involved because it requires the user to not only iterate over all of the data but also consider conditions like whether the pair has been flipped or whether impulses have been reported with the pair. However, this approach of iterating over the data in-place may be more efficient because it doesn't require copying data.</p> +<div class="section" id="extra-contact-data"> +<h3>Extra Contact Data<a class="headerlink" href="#extra-contact-data" title="Permalink to this headline">¶</a></h3> +<p>Since pointers to the actors of a contact pair are provided in contact reports, actor properties can be read directly within the callback. However, the pose and the velocity of an actor usually refer to the time of impact. If for some reasons the velocity after collision response is of interest, then the actor can not provide that information. Similarly, it is not possible to get the actor velocity or the pose at impact if those properties were changed by the user while the simulation was running (in such a case the newly set property values will be returned). Last but not least, if CCD with multiple passes is enabled, then a fast moving object might bounce on and off the same object multiple times. The object poses and velocities for each such impact can not get extracted from the actor pointers in the callback. For these scenarios, the PhysX SDK provides an additional contact stream that can hold all sorts of extra information related to the contact pair. This extra information is requested per pair through the pair flags <em>PxPairFlags</em> (see the API documentation of <em>PxPairFlag::ePRE_SOLVER_VELOCITY</em>, <em>::ePOST_SOLVER_VELOCITY</em>, <em>::eCONTACT_EVENT_POSE</em> for details). If requested, the extra data stream will be available as a member of the <em>PxContactPairHeader</em> structure. The stream can then be parsed by using the predefined iterator <em>PxContactPairExtraDataIterator</em> or by some custom parsing code (see the implementation of <em>PxContactPairExtraDataIterator</em> for details about the format of the stream).</p> +<p>Example code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">MySimulationCallback</span><span class="o">::</span><span class="n">onContact</span><span class="p">(</span><span class="k">const</span> <span class="n">PxContactPairHeader</span><span class="o">&</span> <span class="n">pairHeader</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxContactPair</span><span class="o">*</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">nbPairs</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PxContactPairExtraDataIterator</span> <span class="n">iter</span><span class="p">(</span><span class="n">pairHeader</span><span class="p">.</span><span class="n">extraDataStream</span><span class="p">,</span> + <span class="n">pairHeader</span><span class="p">.</span><span class="n">extraDataStreamSize</span><span class="p">);</span> + <span class="k">while</span><span class="p">(</span><span class="n">iter</span><span class="p">.</span><span class="n">nextItemSet</span><span class="p">())</span> + <span class="p">{</span> + <span class="k">if</span> <span class="p">(</span><span class="n">iter</span><span class="p">.</span><span class="n">postSolverVelocity</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">PxVec3</span> <span class="n">linearVelocityActor0</span> <span class="o">=</span> <span class="n">iter</span><span class="p">.</span><span class="n">postSolverVelocity</span><span class="o">-></span><span class="n">linearVelocity</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> + <span class="n">PxVec3</span> <span class="n">linearVelocityActor1</span> <span class="o">=</span> <span class="n">iter</span><span class="p">.</span><span class="n">postSolverVelocity</span><span class="o">-></span><span class="n">linearVelocity</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> + <span class="p">...</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="continuous-collision-detection"> +<span id="id2"></span><h2>Continuous Collision Detection<a class="headerlink" href="#continuous-collision-detection" title="Permalink to this headline">¶</a></h2> +<p>When continuous collision detection (or CCD) is turned on, the affected rigid bodies will not go through other objects at high velocities (a problem also known as tunnelling). To enable CCD, three things need to be happen:</p> +<ol class="arabic"> +<li><p class="first">CCD needs to be turned on at scene level:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physx</span><span class="p">;</span> +<span class="p">...</span> +<span class="n">PxSceneDesc</span> <span class="n">desc</span><span class="p">;</span> +<span class="n">desc</span><span class="p">.</span><span class="n">flags</span> <span class="o">|=</span> <span class="n">PxSceneFlag</span><span class="o">::</span><span class="n">eENABLE_CCD</span><span class="p">;</span> +<span class="p">...</span> +</pre></div> +</div> +</li> +<li><p class="first">Pairwise CCD needs to be enabled in the pair filter:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">PxFilterFlags</span> <span class="nf">filterShader</span><span class="p">(</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes0</span><span class="p">,</span> + <span class="n">PxFilterData</span> <span class="n">filterData0</span><span class="p">,</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes1</span><span class="p">,</span> + <span class="n">PxFilterData</span> <span class="n">filterData1</span><span class="p">,</span> + <span class="n">PxPairFlags</span><span class="o">&</span> <span class="n">pairFlags</span><span class="p">,</span> + <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> + <span class="n">PxU32</span> <span class="n">constantBlockSize</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eSOLVE_CONTACT</span><span class="p">;</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eDETECT_DISCRETE_CONTACT</span><span class="p">;</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eDETECT_CCD_CONTACT</span><span class="p">;</span> + <span class="k">return</span> <span class="n">PxFilterFlags</span><span class="p">();</span> +<span class="p">}</span> + +<span class="p">...</span> + +<span class="n">desc</span><span class="p">.</span><span class="n">filterShader</span> <span class="o">=</span> <span class="n">testCCDFilterShader</span><span class="p">;</span> +<span class="n">physx</span><span class="o">-></span><span class="n">createScene</span><span class="p">(</span><span class="n">desc</span><span class="p">);</span> +</pre></div> +</div> +</li> +<li><p class="first">CCD need to be enabled for each PxRigidBody that requires CCD:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidBody</span><span class="o">*</span> <span class="n">body</span><span class="p">;</span> +<span class="p">...</span> +<span class="n">body</span><span class="o">-></span><span class="n">setRigidBodyFlag</span><span class="p">(</span><span class="n">PxRigidBodyFlag</span><span class="o">::</span><span class="n">eENABLE_CCD</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +</li> +</ol> +<p>Once enabled, CCD only activates between shapes whose relative speeds are above the sum of their respective CCD velocity thresholds. These velocity thresholds are automatically calculated based on the shape's properties and support non-uniform scales.</p> +<div class="section" id="contact-notification-and-modification"> +<h3>Contact Notification and Modification<a class="headerlink" href="#contact-notification-and-modification" title="Permalink to this headline">¶</a></h3> +<p>CCD supports the full set of contact notification events that are supported with the discrete collision detection. For details on contact notification, see the documentation for Callbacks.</p> +<p>CCD supports contact modification. To listen to these modify callbacks, derive from the class PxCCDContactModifyCallback:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyCCDContactModification</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxCCDContactModifyCallback</span> +<span class="p">{</span> + <span class="p">...</span> + <span class="kt">void</span> <span class="n">onCCDContactModify</span><span class="p">(</span><span class="n">PxContactModifyPair</span><span class="o">*</span> <span class="k">const</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">);</span> +<span class="p">};</span> +</pre></div> +</div> +<p>And then implement the function onContactModify of PxContactModifyCallback:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">MyContactModification</span><span class="o">::</span><span class="n">onContactModify</span><span class="p">(</span><span class="n">PxContactModifyPair</span> <span class="o">*</span><span class="k">const</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">count</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="p">...</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This onContactModify callback operates using the same semantics as the discrete collision detection contact modification callbacks. For further details, please refer to the documentation on Callbacks.</p> +<p>As with discrete collision detection, CCD will only emit contact modification events for a given pair if the user has specified the pair flag PxPairFlag::eMODIFY_CONTACTS in the filter shader.</p> +</div> +<div class="section" id="triggers"> +<h3>Triggers<a class="headerlink" href="#triggers" title="Permalink to this headline">¶</a></h3> +<p>Currently, shapes flagged with PxShapeFlag::eTRIGGER_SHAPE will not be included in CCD. However, it is possible to get trigger events from CCD by not flagging trigger shapes as PxShapeFlag::eTRIGGER_SHAPE and instead configuring the filter shaders to return the following state for pairs involving trigger shapes:</p> +<blockquote> +<div>pairFlags = PxPairFlag::eTRIGGER_DEFAULT | PxPairFlag::eDETECT_CCD_CONTACT; +return PxFilterFlag::eDEFAULT;</div></blockquote> +<p>It should be noted that not flagging shapes as PxShapeFlag::eTRIGGER_SHAPE can result in the triggers being more expensive. Therefore, this workaround should be reserved for use only in situations where important trigger events will be missed without CCD.</p> +</div> +<div class="section" id="tuning-ccd"> +<h3>Tuning CCD<a class="headerlink" href="#tuning-ccd" title="Permalink to this headline">¶</a></h3> +<p>The CCD should generally work without any tuning. However, there are 4 properties that can be adjusted:</p> +<ol class="arabic simple"> +<li>PxSceneDesc.ccdMaxPasses: This variable controls the number of CCD passes we perform. This is defaulted to 1, meaning that all objects are attempted to be updated to the TOI of their first contact. Any remaining time after the TOI of their first contact will be dropped. Increasing this value permits the CCD to run multiple passes. This reduces the likelihood of time being dropped but can increase the cost of the CCD.</li> +<li>PxRigidBody::setMinCCDAdvanceCoefficient(PxReal advanceCoefficient): This method allows you to adjust the amount by which the CCD advances objects in a given pass. By default, this value is 0.15, meaning that CCD will advance an object by the 0.15 * ccdThreshold, where ccdThreshold is a value computed per-shape that acts as a lower-bound of the maximum amount of time that could be consumed that before there is a chance that the object could have tunnelled. The default value of 0.15 improves the fluidity of motion without risking missed collisions. Reducing this value can negatively impact fluidity but will reduce the likelihood of objects clipping at the end of a frame. Increasing this value may increase the likelihood of objects tunnelling. This value should only be set in the range [0,1].</li> +<li>Enabling the flag PxSceneFlag::eDISABLE_CCD_RESWEEP on the PxSceneDesc.flags: Enabling this flag disables CCD resweeps. This can result in missed collisions as the result of ricochets but has the potential to reduce the overhead of the CCD. In general, enabling this advancement mode still guarantees that objects will not pass through the static environment but no longer guarantees that dynamic objects with CCD enabled will not pass through each-other.</li> +<li>PxRigidBody::setRigidBodyFlag(PxRigidBodyFlag::eENABLE_CCD_FRICTION, true): Enabling this flag enables the application of friction forces in the CCD. This is disabled by default. As the CCD operates using only linear motion, enabling friction inside CCD can cause visual artefacts.</li> +</ol> +</div> +<div class="section" id="performance-implications"> +<h3>Performance Implications<a class="headerlink" href="#performance-implications" title="Permalink to this headline">¶</a></h3> +<p>Enabling CCD on a scene/all bodies in a scene should be relatively efficient but it will have some performance impact even when all the objects in the scene are moving relatively slowly. A great deal of effort has been put into optimizing the CCD and as a result, this additional overhead should only constitute a very small portion of the overall simulation time when the objects are moving slowly. As the objects' velocities increase, the CCD overhead will increase, especially if there are a lot of high-speed objects in close proximity. Increasing the number of CCD passes can make the CCD more expensive although the CCD will terminate early if the additional passes aren't required.</p> +</div> +<div class="section" id="limitations"> +<h3>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h3> +<p>The CCD system is a best-effort conservative advancement scheme. It runs a finite number of CCD substeps (defaulted to 1) and drops any remaining time. Usually, time is only dropped on high-speed objects at the moment of impact so it is not noticeable. However, this artefact can become noticeable if you simulate an object that is sufficiently small/thin relative to the simulation time-step that the object could tunnel if it was accelerated by gravity from rest for 1 frame, i.e. a paper-thin rigid body. Such an object would always be moving at above its CCD velocity threshold and could result in a large proportion of simulation time being dropped for that object and any objects in the same island as it (any objects whose bounds overlap the bounds of that object). This could cause a noticeable slow-down/stuttering effect caused by the objects in that island becoming noticeably out-of-sync with the rest of the simulation. It is therefore recommended that paper-thin/tiny objects should be avoided if possible.</p> +<p>It is also recommended that you filter away CCD interactions between bodies that are constrained together, e.g. limbs in the same ragdoll. Allowing CCD interactions between limbs of the same ragdoll could increase the cost of CCD and also potentially cause time to be dropped unnecessarily. CCD interactions are automatically disabled between links in an articulation.</p> +</div> +</div> +<div class="section" id="raycast-ccd"> +<h2>Raycast CCD<a class="headerlink" href="#raycast-ccd" title="Permalink to this headline">¶</a></h2> +<p>The PhysX SDK supports an alternative CCD implementation based on simple raycasts. This "raycast CCD" algorithm is available in PhysX Extensions, and it is demonstrated in a snippet ("SnippetRaycastCCD"). Contrary to the built-in CCD algorithm implemented within the PhysX SDK, this cheaper and simpler alternative version is fully implemented outside of the SDK itself.</p> +<p>After the traditional simulate/fetchResults calls, the system performs raycasts from the shapes' center positions to double-check that they did not tunnel. If tunnelling is detected for an object, it is moved back to a previous position along the ray, in an overlap position. Then next frame, the SDK's contact generation takes over and generates a convincing motion. There are some subtle details not described here, but this is how it works in a nutshell.</p> +<p>Since it is raycast-based, the solution is not perfect. In particular, small dynamic objects can still go through the static world if the ray goes through a crack between edges, or a small hole in the world (like the keyhole from a door). Also, dynamic-vs-dynamic CCD is very approximate. It only works well for fast-moving dynamic objects colliding against slow-moving dynamic objects. Other known limitations are that it is currently only implemented for PxRigidDynamic objects (not for PxArticulationLink), and for simple actors with one shape (not for "compounds").</p> +<p>However the implementation should be able to prevent important objects from leaving the game world, provided the world is watertight. The code is very small, easy to follow or modify, and its performance is often better overall than for the built-in CCD. So it can be a valuable alternative if the default CCD becomes too expensive.</p> +</div> +<div class="section" id="speculative-ccd"> +<h2>Speculative CCD<a class="headerlink" href="#speculative-ccd" title="Permalink to this headline">¶</a></h2> +<p>In addition to sweep-based CCD, PhysX also provides a cheaper but less robust approach called speculative CCD. This approach functions differently to the sweep-based CCD in that it operates entirely as part of the discrete simulation by inflating contact offsets based on object motion and depending on the constraint solver to ensure that objects do not tunnel through each-other.</p> +<p>This approach generally works well and, unlike the sweep-based CCD, it is legal to enable speculative CCD on kinematic actors. However, there are cases where it can fail to ensure objects do not pass through each-other. As an example, if the constraint solver accelerates an actor (as a result of a collision or joint) such that the actor passes entirely through objects during that time-step, speculative CCD can result in tunneling.</p> +<p>To enable this feature, raise PxRigidBodyFlag::eENABLE_SPECULATIVE_CCD on the rigid body that requires CCD:</p> +<div class="highlight-c++"><div class="highlight"><pre> <span class="n">PxRigidBody</span><span class="o">*</span> <span class="n">body</span><span class="p">;</span> +<span class="p">...</span> +<span class="n">body</span><span class="o">-></span><span class="n">setRigidBodyFlag</span><span class="p">(</span><span class="n">PxRigidBodyFlag</span><span class="o">::</span><span class="n">eENABLE_SPECULATIVE_CCD</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Unlike the sweep-based CCD, this form of CCD does not require settings to be raised on either the scene or on the pair in the filter shader.</p> +<p>Note that this approach works best with PCM collision detection. It may not function as well if the legacy SAT-based collision detection approach is used.</p> +<p>This feature can work in conjunction with the sweep-based CCD, e.g. if a fast-moving kinematic has speculative CCD enabled but dynamic rigid bodies use sweep-based CCD. However, if speculative CCD is used on kinematics in conjunction with sweep-based CCD, it is important to ensure that interactions between the kinematic actor using speculative contacts and the CCD-enabled dynamic actors do not also enable sweep-based CCD interactions otherwise the sweep-based CCD may overrule the speculative CCD, leading to poor behavior.</p> +</div> +<div class="section" id="persistent-contact-manifold-pcm"> +<h2>Persistent Contact Manifold (PCM)<a class="headerlink" href="#persistent-contact-manifold-pcm" title="Permalink to this headline">¶</a></h2> +<p>The PhysX SDK provides two types of collision detection:</p> +<ol class="arabic simple"> +<li>Default collision detection</li> +</ol> +<p>The default collision detection system uses a mixture of SAT (Separating Axis Theorem) and distance-based collision detection to generate full contact manifolds. It generates all the potential contacts in one frame, so it lends itself better to stable stacking. This approach is stable for small contact offsets and rest offsets but may not generate the correct contact points when large offsets are used because it approximates the contact points in these situations by plane shifting.</p> +<ol class="arabic simple" start="2"> +<li>Persistent Contact Manifold (PCM)</li> +</ol> +<p>PCM is a fully distance-based collision detection system. PCM generates a full manifold of contacts when two shapes first come into contact. It recycles and updates the existing contacts from the previous frame in the manifold and then it generates a new contact in the subsequent frame if the shapes move relative to each-other more than a threshold amount or if a contact was dropped from the manifold. If too many contacts are dropped from the manifold due to a large amount of relative motion in a frame, then full manifold generation is re-run. This approach is quite efficient in terms of performance and memory. However, because PCM potentially generates fewer contacts than the default collision detection, it might reduce stacking stability when simulating tall stacks with insufficient solver iterations. As this approach is distance-based, it will generate the correct contact points for arbitrary contact offsets/rest offsets.</p> +<p>To enable PCM, set the flag in the PxSceneDesc::flags:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSceneDesc</span> <span class="n">sceneDesc</span><span class="p">;</span> + +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">|=</span> <span class="n">PxSceneFlag</span><span class="o">::</span><span class="n">eENABLE_PCM</span><span class="p">;</span> +</pre></div> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Advanced Collision Detection</a><ul> +<li><a class="reference internal" href="#tuning-shape-collision-behavior">Tuning Shape Collision Behavior</a></li> +<li><a class="reference internal" href="#contact-modification">Contact Modification</a></li> +<li><a class="reference internal" href="#contact-reporting">Contact reporting</a><ul> +<li><a class="reference internal" href="#contact-reports-and-ccd">Contact Reports and CCD</a></li> +</ul> +</li> +<li><a class="reference internal" href="#extracting-contact-information">Extracting Contact information</a><ul> +<li><a class="reference internal" href="#extra-contact-data">Extra Contact Data</a></li> +</ul> +</li> +<li><a class="reference internal" href="#continuous-collision-detection">Continuous Collision Detection</a><ul> +<li><a class="reference internal" href="#contact-notification-and-modification">Contact Notification and Modification</a></li> +<li><a class="reference internal" href="#triggers">Triggers</a></li> +<li><a class="reference internal" href="#tuning-ccd">Tuning CCD</a></li> +<li><a class="reference internal" href="#performance-implications">Performance Implications</a></li> +<li><a class="reference internal" href="#limitations">Limitations</a></li> +</ul> +</li> +<li><a class="reference internal" href="#raycast-ccd">Raycast CCD</a></li> +<li><a class="reference internal" href="#speculative-ccd">Speculative CCD</a></li> +<li><a class="reference internal" href="#persistent-contact-manifold-pcm">Persistent Contact Manifold (PCM)</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Simulation.html" + title="previous chapter">Simulation</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Joints.html" + title="next chapter">Joints</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" /> + <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="Joints.html" title="Joints" + >next</a></li> + <li class="right" > + <a href="Simulation.html" title="Simulation" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Articulations.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Articulations.html new file mode 100644 index 00000000..909fa1ce --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Articulations.html @@ -0,0 +1,193 @@ +<!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>Articulations — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Scene Origin" href="OriginShift.html" /> + <link rel="prev" title="Joints" href="Joints.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="OriginShift.html" title="Scene Origin" + accesskey="N">next</a></li> + <li class="right" > + <a href="Joints.html" title="Joints" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="articulations"> +<span id="id1"></span><h1>Articulations<a class="headerlink" href="#articulations" title="Permalink to this headline">¶</a></h1> +<p>An articulation is a single actor comprising a set of links (each of which behaves like a rigid body) connected together with special joints. Every articulation has a tree-like structure - so there can be no loops or breaks. Their primary use is modelling physically actuated characters. They support higher mass ratios, more accurate drive models, have better dynamic stability and a more robust recovery from joint separation than standard PhysX joints. However, they are considerably more expensive to simulate.</p> +<p>Although articulations do not directly build on joints, they use very similar configuration mechanisms. In this section we assume familiarity with PhysX joints.</p> +<div class="section" id="creating-an-articulation"> +<h2>Creating an Articulation<a class="headerlink" href="#creating-an-articulation" title="Permalink to this headline">¶</a></h2> +<p>To create an articulation, first create the articulation actor without links:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxArticulation</span><span class="o">*</span> <span class="n">articulation</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createArticulation</span><span class="p">();</span> +</pre></div> +</div> +<p>Then add links one by one, each time specifying a parent link (NULL for the parent of the initial link), and the pose of the new link:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxArticulationLink</span><span class="o">*</span> <span class="n">link</span> <span class="o">=</span> <span class="n">articulation</span><span class="o">-></span><span class="n">createLink</span><span class="p">(</span><span class="n">parent</span><span class="p">,</span> <span class="n">linkPose</span><span class="p">);</span> +<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">link</span><span class="p">,</span> <span class="n">linkGeometry</span><span class="p">,</span> <span class="n">material</span><span class="p">);</span> +<span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">updateMassAndInertia</span><span class="p">(</span><span class="o">*</span><span class="n">link</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>Articulation links have a restricted subset of the functionality of rigid bodies. They may not be kinematic, and they do not support damping, velocity clamping, or contact force thresholds. Sleep state and solver iteration counts are properties of the entire articulation rather than the individual links.</p> +<p>Each time a link is created beyond the first, a <em>PxArticulationJoint</em> is created between it and its parent. Specify the joint frames for each joint, in exactly the same way as for a PxJoint:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxArticulationJoint</span><span class="o">*</span> <span class="n">joint</span> <span class="o">=</span> <span class="n">link</span><span class="o">-></span><span class="n">getInboundJoint</span><span class="p">();</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setParentPose</span><span class="p">(</span><span class="n">parentAttachment</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setChildPose</span><span class="p">(</span><span class="n">childAttachment</span><span class="p">);</span> +</pre></div> +</div> +<p>Finally, add the articulation to the scene:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="p">.</span><span class="n">addArticulation</span><span class="p">(</span><span class="n">articulation</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="articulation-joints"> +<h2>Articulation Joints<a class="headerlink" href="#articulation-joints" title="Permalink to this headline">¶</a></h2> +<p>The only form of articulation joint currently supported is an anatomical joint, whose properties are similar to D6 joint configured for a typical rag doll (see <a class="reference internal" href="Joints.html#pxd6joint"><em>D6 Joint</em></a>). Specifically, the joint is a spherical joint, with angular drive, a twist limit around the child joint frame's x-axis, and an elliptical swing cone limit around the parent joint frame's x-axis. The configuration of these properties is very similar to a D6 or spherical joint, but the options provided are slightly different.</p> +<p>The swing limit is a hard elliptical cone limit which does not support spring or restitution from movement perpendicular to the limit surface. You can set the limit ellipse angle as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setSwingLimit</span><span class="p">(</span><span class="n">yAngle</span><span class="p">,</span> <span class="n">zAngle</span><span class="p">);</span> +</pre></div> +</div> +<p>for the limit angles around y and z. Unlike the PxJoint cone limit the limit provides a tangential spring to limit movement of the axis along the limit surface. Once configured, enable the swing limit:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setSwingLimitEnabled</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>The twist limit allows configuration of upper and lower angles:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setTwistLimit</span><span class="p">(</span><span class="n">lower</span><span class="p">,</span> <span class="n">upper</span><span class="p">);</span> +</pre></div> +</div> +<p>and again you must explicitly enable it:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setTwistLimitEnabled</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>As usual with joint limits, it is good practice to use a sufficient limit contactDistance value that the solver will start to enforce the limit before the limit threshold is exceeded.</p> +<p>Articulation joints are not breakable, and it is not possible to retrieve the constraint force applied at the joint.</p> +</div> +<div class="section" id="driving-an-articulation"> +<h2>Driving an Articulation<a class="headerlink" href="#driving-an-articulation" title="Permalink to this headline">¶</a></h2> +<p>Articulations are driven through joint acceleration springs. You can set an orientation target, an angular velocity target, and spring and damping parameters that control how strongly the joint drives towards the target. You can also set compliance values, indicating how strongly a joint resists acceleration. A compliance near zero indicates very strong resistance, and a compliance of 1 indicates no resistance.</p> +<p>Articulations are driven in two phases. First the joint spring forces are applied (we use the term <em>internal</em> forces for these) and then any <em>external</em> forces such as gravity and contact forces. You may supply different compliance values at each joint for each phase.</p> +<p>Note that with joint acceleration springs, the required strength of the spring is estimated using just the mass of the two bodies connected by the joint. By contrast, articulation drive springs account for the masses of all the bodies in the articulation, and any stiffness from actuation at other joints. This estimation is an iterative process, controlled using the <em>externalDriveIterations</em> and <em>internalDriveIterations</em> properties of the PxArticulation class.</p> +<p>Instead of setting the target quaternion for the joint drive, it is possible to set the orientation error term directly as a rotation vector. The value is set as the imaginary part of the target quaternion, with the real part set to 0.</p> +<blockquote> +<div><blockquote> +<div>joint->setDriveType(PxArticulationJointDriveType::eERROR); +joint->setTargetOrientation(PxQuat(error.x, error.y, error.z, 0));</div></blockquote> +<p>This allows the spring to be driven with a larger positional error than can be generated by the difference between 2 quaternions. Obtain the same behavior as with target quaternions by computing the error from the target quaternion, link frames, and joint frames as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxTransform</span> <span class="n">cA2w</span> <span class="o">=</span> <span class="n">parentPose</span><span class="p">.</span><span class="n">transform</span><span class="p">(</span><span class="n">joint</span><span class="p">.</span><span class="n">parentPose</span><span class="p">);</span> <span class="c1">// parent attachment frame</span> +<span class="n">PxTransform</span> <span class="n">cB2w</span> <span class="o">=</span> <span class="n">childPose</span><span class="p">.</span><span class="n">transform</span><span class="p">(</span><span class="n">joint</span><span class="p">.</span><span class="n">childPose</span><span class="p">);</span> <span class="c1">// child attachment frame</span> +<span class="n">transforms</span><span class="p">.</span><span class="n">cB2cA</span> <span class="o">=</span> <span class="n">transforms</span><span class="p">.</span><span class="n">cA2w</span><span class="p">.</span><span class="n">transformInv</span><span class="p">(</span><span class="n">transforms</span><span class="p">.</span><span class="n">cB2w</span><span class="p">);</span> <span class="c1">// relative transform</span> +<span class="k">if</span><span class="p">(</span><span class="n">transforms</span><span class="p">.</span><span class="n">cB2cA</span><span class="p">.</span><span class="n">q</span><span class="p">.</span><span class="n">w</span><span class="o"><</span><span class="mi">0</span><span class="p">)</span> <span class="c1">// shortest path path</span> + <span class="n">transforms</span><span class="p">.</span><span class="n">cB2cA</span><span class="p">.</span><span class="n">q</span> <span class="o">=</span> <span class="o">-</span><span class="n">transforms</span><span class="p">.</span><span class="n">cB2cA</span><span class="p">.</span><span class="n">q</span><span class="p">;</span> + +<span class="c1">// rotation vector from relative transform to drive pose</span> +<span class="n">PxVec3</span> <span class="n">error</span> <span class="o">=</span> <span class="n">log</span><span class="p">(</span><span class="n">j</span><span class="p">.</span><span class="n">targetPosition</span> <span class="o">*</span> <span class="n">cB2cA</span><span class="p">.</span><span class="n">q</span><span class="p">.</span><span class="n">getConjugate</span><span class="p">());</span> +</pre></div> +</div> +</div></blockquote> +</div> +<div class="section" id="articulation-projection"> +<h2>Articulation Projection<a class="headerlink" href="#articulation-projection" title="Permalink to this headline">¶</a></h2> +<p>When any of the joints in an articulation separate beyond a specified threshold, the articulation is projected back together automatically. Projection is an iterative process, and the PxArticulation functions <em>PxArticulation::setSeparationTolerance()</em> and <em>PxArticulation::setMaxProjectionIterations()</em> control when projection occurs and trade cost for robustness.</p> +</div> +<div class="section" id="articulations-and-sleeping"> +<h2>Articulations and Sleeping<a class="headerlink" href="#articulations-and-sleeping" title="Permalink to this headline">¶</a></h2> +<p>Like rigid dynamic objects, articulations are also put into a sleep state if their energy falls below a certain threshold for a period of time. In general, all the points in the section <a class="reference internal" href="RigidBodyDynamics.html#sleeping"><em>Sleeping</em></a> apply to articulations as well. The main difference is that articulations can only go to sleep if each individual articulation link fulfills the sleep criteria.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Articulations</a><ul> +<li><a class="reference internal" href="#creating-an-articulation">Creating an Articulation</a></li> +<li><a class="reference internal" href="#articulation-joints">Articulation Joints</a></li> +<li><a class="reference internal" href="#driving-an-articulation">Driving an Articulation</a></li> +<li><a class="reference internal" href="#articulation-projection">Articulation Projection</a></li> +<li><a class="reference internal" href="#articulations-and-sleeping">Articulations and Sleeping</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Joints.html" + title="previous chapter">Joints</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="OriginShift.html" + title="next chapter">Scene Origin</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" /> + <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="OriginShift.html" title="Scene Origin" + >next</a></li> + <li class="right" > + <a href="Joints.html" title="Joints" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/BestPractices.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/BestPractices.html new file mode 100644 index 00000000..4ea17fb8 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/BestPractices.html @@ -0,0 +1,462 @@ +<!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>Best Practices Guide — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Migrating From PhysX SDK 2.x to 3.x" href="MigrationFrom28.html" /> + <link rel="prev" title="Extending Serialization" href="ExtendingSerialization.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="MigrationFrom28.html" title="Migrating From PhysX SDK 2.x to 3.x" + accesskey="N">next</a></li> + <li class="right" > + <a href="ExtendingSerialization.html" title="Extending Serialization" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="best-practices-guide"> +<span id="bestpractices"></span><h1>Best Practices Guide<a class="headerlink" href="#best-practices-guide" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This chapter covers a number of best practices for the PhysX SDK to assist in diagnosing and fixing frequently encountered issues.</p> +</div> +<div class="section" id="debugging"> +<h2>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline">¶</a></h2> +<p>The PhysX SDK contains a few debugging helpers. They can be used to make sure the scenes are properly set up.</p> +<div class="section" id="use-checked-builds-and-the-error-stream"> +<h3>Use checked builds and the error stream<a class="headerlink" href="#use-checked-builds-and-the-error-stream" title="Permalink to this headline">¶</a></h3> +<p>The PhysX SDK has different build configurations: Debug, Checked, Release, Profile. To make sure that the scene is properly set up without warnings or errors, use either the Debug or Checked builds, and monitor the error callback. Please refer to the <a class="reference internal" href="API.html#errorreporting"><em>Error Reporting</em></a> chapter for details. Note that some checks can be expensive and thus they are not performed in Release or Profile builds. If the SDK silently fails or even crashes in a Release build, please switch to Debug or Checked builds to ensure this is not caused by an uncaught error.</p> +</div> +<div class="section" id="visualizing-physics-data"> +<h3>Visualizing physics data<a class="headerlink" href="#visualizing-physics-data" title="Permalink to this headline">¶</a></h3> +<p>Use the PhysX Visual Debugger (PVD) to see what PhysX is seeing and make sure the physics data is what you expect it to be. Please refer to the <a class="reference internal" href="VisualDebugger.html#physxvisualdebugger"><em>PhysX Visual Debugger (PVD)</em></a> chapter for details. Note that this is only available in Debug, Checked and Profile builds.</p> +</div> +<div class="section" id="visualizing-physics-data-2"> +<h3>Visualizing physics data (2)<a class="headerlink" href="#visualizing-physics-data-2" title="Permalink to this headline">¶</a></h3> +<p>An alternative to PVD is the built-in debug visualization system. Please refer to the <a class="reference internal" href="DebugVisualization.html#debugvisualization"><em>Debug Visualization</em></a> chapter for details. This option is available with all build configurations.</p> +</div> +<div class="section" id="limiting-coordinates"> +<h3>Limiting coordinates<a class="headerlink" href="#limiting-coordinates" title="Permalink to this headline">¶</a></h3> +<p>Bugs in applications, or issues in content creation, can sometimes result in object placement at unexpected coordinates. We recommend the use of PxSceneDesc::sanityBounds, to generate reports when objects are inserted at positions beyond what your application expects, or when application code moves them to such unexpected positions. Note that these bounds only apply to application updates of actor coordinates, not updates by the simulation engine.</p> +</div> +</div> +<div class="section" id="performance-issues"> +<h2>Performance Issues<a class="headerlink" href="#performance-issues" title="Permalink to this headline">¶</a></h2> +<p>The PhysX SDK has been optimized a lot in the past dot releases. However, there still exist various performance pitfalls that the user should be aware of.</p> +<div class="section" id="use-profile-builds-to-identify-performance-bottlenecks"> +<h3>Use profile builds to identify performance bottlenecks<a class="headerlink" href="#use-profile-builds-to-identify-performance-bottlenecks" title="Permalink to this headline">¶</a></h3> +<p>The PhysX SDK has different build configurations: Debug, Checked, Release, Profile. To identify performance bottlenecks, please use Profile builds and PVD. Use the <em>PxPvdInstrumentationFlag::ePROFILE</em> only, since enabling the other connection flags might negatively affect performance. Please refer to the <a class="reference internal" href="VisualDebugger.html#physxvisualdebugger"><em>PhysX Visual Debugger (PVD)</em></a> chapter for details.</p> +</div> +<div class="section" id="use-release-builds-for-final-performance-tests"> +<h3>Use release builds for final performance tests<a class="headerlink" href="#use-release-builds-for-final-performance-tests" title="Permalink to this headline">¶</a></h3> +<p>The PhysX SDK has different build configurations: Debug, Checked, Release, Profile. The Release builds are the most optimal. If you encounter a performance issue while using other builds, please switch to Release builds and check if the problem is still there.</p> +</div> +<div class="section" id="disable-debug-visualization-in-final-release-builds"> +<h3>Disable debug visualization in final/release builds<a class="headerlink" href="#disable-debug-visualization-in-final-release-builds" title="Permalink to this headline">¶</a></h3> +<p>Debug visualization is great for debugging but it can have a significant performance impact. Make sure it is disabled in your final/release builds. Please refer to the <a class="reference internal" href="DebugVisualization.html#debugvisualization"><em>Debug Visualization</em></a> chapter for details.</p> +</div> +<div class="section" id="debug-visualization-is-very-slow"> +<h3>Debug visualization is very slow<a class="headerlink" href="#debug-visualization-is-very-slow" title="Permalink to this headline">¶</a></h3> +<p>Debug visualization can be very slow, because both the code gathering the debug data and the code rendering it is usually not optimal. Use a culling box to limit the amount of data the SDK gathers and sends to the renderer. Please refer to the <a class="reference internal" href="DebugVisualization.html#debugvisualization"><em>Debug Visualization</em></a> chapter for details.</p> +</div> +<div class="section" id="consider-using-tight-bounds-for-convex-meshes"> +<h3>Consider using tight bounds for convex meshes<a class="headerlink" href="#consider-using-tight-bounds-for-convex-meshes" title="Permalink to this headline">¶</a></h3> +<p>By default PhysX computes approximate (loose) bounds around convex objects. Using PxConvexMeshGeometryFlag::eTIGHT_BOUNDS enables smaller/tighter bounds, which are more expensive to compute but can result in improved simulation performance when a lot of convex objects are interacting with each other. Please refer to the <a class="reference internal" href="Geometry.html#geometry"><em>Geometry</em></a> chapter for details.</p> +</div> +<div class="section" id="use-scratch-buffers"> +<h3>Use scratch buffers<a class="headerlink" href="#use-scratch-buffers" title="Permalink to this headline">¶</a></h3> +<p>The PxScene::simulate function accepts optional scratch buffers that can be used to reduce temporary allocations and improve simulation performance. Please refer to the <a class="reference internal" href="Simulation.html#simulation"><em>Simulation</em></a> chapter for details.</p> +</div> +<div class="section" id="use-the-proper-mid-phase-algorithm"> +<h3>Use the proper mid-phase algorithm<a class="headerlink" href="#use-the-proper-mid-phase-algorithm" title="Permalink to this headline">¶</a></h3> +<p>PxCookingParams::midphaseDesc can be used to select the desired mid-phase structure. It is a good idea to try the different options and see which one works best for you. Generally speaking the new PxMeshMidPhase::eBVH34 introduced in PhysX 3.4 has better performance for scene queries against large triangle meshes. Please refer to the <a class="reference internal" href="Geometry.html#geometry"><em>Geometry</em></a> chapter for details.</p> +</div> +<div class="section" id="use-the-proper-narrow-phase-algorithm"> +<h3>Use the proper narrow-phase algorithm<a class="headerlink" href="#use-the-proper-narrow-phase-algorithm" title="Permalink to this headline">¶</a></h3> +<p>PxSceneFlag::eENABLE_PCM enables an incremental "persistent contact manifold" algorithm, which is often faster than the previous implementation. PCM should be the default algorithm since PhysX 3.4, but you can also try to enable it in previous versions like 3.3.</p> +</div> +<div class="section" id="use-the-proper-broad-phase-algorithm"> +<h3>Use the proper broad-phase algorithm<a class="headerlink" href="#use-the-proper-broad-phase-algorithm" title="Permalink to this headline">¶</a></h3> +<p>PhysX also supports two different broad-phase implementations, selected with PxSceneDesc::broadPhaseType. The different implementations have various performance characteristics, and it is a good idea to experiment with both and find which one works best for you. Please refer to the <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollision"><em>Rigid Body Collision</em></a> chapter for details about the different broad-phases.</p> +</div> +<div class="section" id="use-the-scene-query-and-simulation-flags"> +<h3>Use the scene-query and simulation flags<a class="headerlink" href="#use-the-scene-query-and-simulation-flags" title="Permalink to this headline">¶</a></h3> +<p>If a shape is only used for scene-queries (raycasts, etc), disable its simulation flag. If a shape is only used for simulation (e.g. it will never be raycasted against), disable its scene-query flag. This is good for both memory usage and performance. Please refer to the <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollision"><em>Rigid Body Collision</em></a> chapter for details.</p> +</div> +<div class="section" id="tweak-the-dynamic-tree-rebuild-rate"> +<h3>Tweak the dynamic tree rebuild rate<a class="headerlink" href="#tweak-the-dynamic-tree-rebuild-rate" title="Permalink to this headline">¶</a></h3> +<p>If the PxScene::fetchResults call takes a significant amount of time in scenes containing a lot of dynamic objects, try to increase the PxSceneDesc::dynamicTreeRebuildRateHint parameter. Please refer to the <a class="reference internal" href="SceneQueries.html#scenequeries"><em>Scene Queries</em></a> chapter for details.</p> +</div> +<div class="section" id="use-the-insertion-callback-when-cooking-at-runtime"> +<h3>Use the insertion callback when cooking at runtime<a class="headerlink" href="#use-the-insertion-callback-when-cooking-at-runtime" title="Permalink to this headline">¶</a></h3> +<p>Use PxPhysicsInsertionCallback for objects that are cooked at runtime. This is faster than first writing the data to a file or a memory buffer, and then passing the data to PhysX.</p> +</div> +<div class="section" id="the-well-of-despair"> +<h3>The "Well of Despair"<a class="headerlink" href="#the-well-of-despair" title="Permalink to this headline">¶</a></h3> +<p>One common use-case for a physics engine is to simulate fixed-size time-steps independent of the frame rate that the application is rendered at. If the application is capable of being rendered at a higher frequency than the simulation frequency, the user has the option to render the same simulation state, interpolate frames etc. However, sometimes it is not possible to render the scene at a frequency higher-or-equal to the simulation frequency. At this point, the options are to either run the physics simulation with a larger time-step or to simulate multiple, smaller sub-steps. The latter is generally a preferable solution because changing the size of time-steps in a physics simulation can significantly change perceived behavior. However, when using a sub-stepping approach, one must always be aware of the potential that this has to damage performance.</p> +<p>As an example, let's imagine a game that is running using v-sync at 60FPS. This game is simulating a large number of physics bodies and, as a result, the physics is relatively expensive. In order to meet the 60FPS requirement, the entire frame must be completed within ~16ms. As already mentioned, the physics is reasonably expensive and, in this scenario, takes 9ms to simulate 1/60th of a second. If the game was to suddenly spike, e.g. as a result of some OS activity, saving a check-point or loading a new section of the level, we may miss the deadline for 60FPS. If this happens, we must run additional sub-steps in the physics to catch up the missed time in the next frame. Assuming that the previous frame took 50ms instead of 16ms, we must now simulate 3 sub-steps to be able to simulate all the elapsed time. However, each sub-step takes ~9ms, which means that we will take ~27ms to simulate 50ms. As a result, this frame also misses our 16ms deadline for 60FPS, meaning that the frame including v-sync took 33ms (i.e. 30Hz). We must now simulate 2 sub-steps in the next frame, which takes ~18ms and also misses our 16ms deadline. As a result, we never manage to recover back to 60FPS. In this scenario, our decision to sub-step as a result of a spike has resulted in our application being stuck in a performance trough indefinitely. The application is capable of simulating and rendering at 60FPS but becomes stuck in the so-called "physics well of despair" as a result of substepping.</p> +<p>Problems like this can be alleviated in several ways:</p> +<ul class="simple"> +<li>Decouple the physics simulation from the game's update/render loop. In this case, the physics simulation becomes a scheduled event that occurs at a fixed frequency. This can make player interaction in the scene more difficult and may introduce latency so must be well-thought through. However, using multiple scenes (one synchronous for "important" objects, one asynchronous for "unimportant" objects) can help.</li> +<li>Permit the game to "drop" time when faced with a short-term spike. This may introduce visible motion artifacts if spikes occur frequently.</li> +<li>Introduce slight variations in time-step (e.g. instead of simulating at 1/60th, consider simulating a range between 1/50th and 1/60th). This can introduce non-determinism into the simulation so should be used with caution. If this is done, additional time that must be simulated can potentially be amortized over several frames by simulating slightly larger time-steps.</li> +<li>Consider simplifying the physics scene, e.g. reducing object count, shape complexity, adjusting iteration counts etc. Provided physics simulation is a small portion of the total frame time, the application should find it easier to recover from spikes.</li> +</ul> +</div> +<div class="section" id="pruner-performance-for-streamed-environments"> +<h3>Pruner Performance for Streamed Environments<a class="headerlink" href="#pruner-performance-for-streamed-environments" title="Permalink to this headline">¶</a></h3> +<p>PhysX provides multiple types of pruners, each of which aimed at specific applications. These are:</p> +<ul class="simple"> +<li>Static AABB tree</li> +<li>Dynamic AABB tree</li> +</ul> +<p>By default, the static AABB tree is used for the static objects in the environment and the dynamics AABB tree is used for the dynamic objects in the environment. In general, this approach works well but it must be noted that creating the static AABB tree can be very expensive. As a result, adding, removing or moving any static objects in the environment will result in the static AABB tree being fully recomputed, which can introduce significant performance cost. As a result, we recommend the use of dynamics AABB trees for both static and dynamic pruners in games which stream in the static environment. Additionaly scene query performance against newly added objects can be improved by using PxPruningStructure, which can precompute the AABB structure of inserted objects in offline.</p> +</div> +<div class="section" id="performance-implications-for-multi-threading"> +<h3>Performance Implications for Multi-Threading<a class="headerlink" href="#performance-implications-for-multi-threading" title="Permalink to this headline">¶</a></h3> +<p>The PhysX engine is designed from the ground-up to take advantage of multi-core architectures to accelerate physics simulation. However, this does not mean that more threads are always better. When simulating extremely simple scenes, introducing additional worker threads can detrimentally affect performance. This is because, at its core, PhysX operates around a task queue. When a frame's simulation is started, PhysX dispatches a chain of tasks that encapsulate that frame of physics simulation. At various stages of the physics pipeline, work can be performed in parallel on multiple worker threads. However, if there is insufficient work, there will be little or no parallel execution. In this case, the use of additional worker threads may detrimentally affect performance because the various phases of the pipeline may be run by different worker threads, which may incur some additional overhead depending on the CPU architecture compared to running on just a single worker thread. As a result, developers should measure the performance of the engine with their expected physics loads with different numbers of threads to maximize their performance and make sure that they are making the most of the available processing resources for their game.</p> +</div> +<div class="section" id="memory-allocation"> +<h3>Memory allocation<a class="headerlink" href="#memory-allocation" title="Permalink to this headline">¶</a></h3> +<p>Minimizing dynamic allocation is an important aspect of performance tuning, and PhysX provides several mechanisms to control memory usage.</p> +<p>Reduce allocation used for tracking objects by presizing the capacities of scene data structures, using either PxSceneDesc::limits before creating the scene or the function PxScene::setLimits(). When resizing, the new capacities will be at least as large as required to deal with the objects currently in the scene. These values are only for preallocation and do not represent hard limits, so if you add more objects to the scene than the capacity limits you have set, PhysX will allocate more space.</p> +<p>Much of the memory PhysX uses for simulation is held in a pool of blocks, each 16K in size. You can control the current and maximum size of the pool with the nbContactDataBlocks and maxNbContactDataBlocks members of PxSceneDesc. PhysX will never allocate more than the maximum number of blocks specified, and if there is insufficient memory it will instead simply drop contacts or joint constraints. You can find out how many blocks are currently in use with the getNbContactBlocksUsed() method, and find out the maximum number that have ever been used with the getMaxNbContactDataBlocksUsed() method.</p> +<p>Use PxScene::flushSimulation() to reclaim unused blocks, and to shrink the size of scene data structures to the size presently required.</p> +<p>To reduce temporary allocation performed during simulation, provide physx with a memory block in the simulate() call. The block may be reused by the application after the fetchResults() call which marks the end of simulation. The size of the block must be a multiple of 16K, and it must be 16-byte aligned.</p> +</div> +</div> +<div class="section" id="character-controller-systems-using-scene-queries-and-penetration-depth-computation"> +<h2>Character Controller Systems using Scene Queries and Penetration Depth Computation<a class="headerlink" href="#character-controller-systems-using-scene-queries-and-penetration-depth-computation" title="Permalink to this headline">¶</a></h2> +<p>Implementing a Character Controller (CCT) is a common use case for the PhysX Scene Query (SQ) system. A popular approach is to use sweeps to implement movement logic, +and to improve robustness by using Geometry Queries (GQ) to compute and resolve any penetrations that occur due to object movement that does not account for the presence of the controller, or due to numerical precision issues.</p> +<p><strong>Basic Algorithm:</strong></p> +<ol class="arabic simple"> +<li>Call a SQ-Sweep from the current position of the CCT shape to its goal position.</li> +<li>If no initial overlap is detected, move the CCT shape to the position of the first hit, and adjust the trajectory of the CCT by removing the motion relative to the contact normal of the hit.</li> +<li>Repeat Steps 1 and 2 until the goal is reached, or until an SQ-Sweep in Step 1 detects an initial overlap.</li> +<li>If an SQ-Sweep in Step 1 detects an initial overlap, use the GQ Penetration Depth computation function to generate a direction for depenetration. Move the CCT shape out of penetration and begin again with Step 1.</li> +</ol> +<p><strong>Limitations and Problems</strong></p> +<p>Step 4 of the algorithm above can sometimes run into trouble due to implementation differences in SQ-Sweep, SQ-Overlap and and GQ-Penetration Depth queries. Under certain initial conditions +it is possible that the SQ system will determine that a pair of objects is initially overlapping while the GQ -Penetration Depth computation will report them as disjoint (or vice-versa). Penetration depth calculations involving convex hulls operate by shrinking the convex hull and performing distance calculations between a shape and the shrunken convex hull. To understand the conditions under which this occurs and how to resolve the artefacts, please refer to the diagrams and discussion below. Each diagram represents the initial conditions of two shapes, a Character Controller shape (red boxes), a convex obstacle (black boxes), at the time that Step 1 of the +algorithm above is executed. In the diagrams, the outermost rectangular black box is the convex hull as seen by the SQ algorithms; the inner black box with a dashed line represents the shrunken convex shape +and the black box with rounded corners is the shrunken convex shape inflated by the amount by which we shrunk. These three black boxes are used by the GQ-Penetration Depth computation. Although the example refers to convex hull obstacles, the issue is not exclusive to the convex hull shapes; +the problem is similar for other shape types as well.</p> +<div class="figure align-center"> +<img alt="../_images/SQAndMTDMismatched1.png" src="../_images/SQAndMTDMismatched1.png" /> +</div> +<p><strong>Diagram 1: CCT Shape Barely Touches an Obstacle</strong></p> +<p>In <strong>Diagram 1</strong>, the red box of the CCT is barely touching the outermost black box of the convex obstacle. In this situation the SQ-Sweep will report an initial overlap but the GQ-Penetration Depth function will report no hit, because the red box is not touching the black box with rounded corners.</p> +<p>To resolve this, inflate the CCT shape for the GQ-Penetration Depth calculation to ensure that it detects an overlap and returns a valid normal. Note that after inflating the CCT shape, the GQ-Penetration Depth function will report that the shapes are penetrated more deeply than they actually are, so take this additional penetration into account when depenetrating in Step 4. This may result in some clipping around the corners and edges of convex objects but the CCT's motion should be acceptable. As the corners/edges become more acute, the amount of clipping will increase.</p> +<div class="figure align-center"> +<img alt="../_images/SQAndMTDMismatched2.png" src="../_images/SQAndMTDMismatched2.png" /> +</div> +<p><strong>Diagram 2: CCT Overlaps an Obstacle Slightly</strong></p> +<p><strong>Diagram 2</strong> shows a case where the CCT initially overlaps the outer black box seen by the SQ system, but does not overlap the shrunken shape seen by the GQ-Penetration Depth calculator. The GQ-Penetration Depth system will return the penetration from point c to point b but not from point c to point a. Therefore the CCT may clip through the corner of the convex hull after depenetration. This can be corrected in Step 4.</p> +<div class="figure align-center"> +<img alt="../_images/SQAndMTDMismatched3.png" src="../_images/SQAndMTDMismatched3.png" /> +</div> +<p><strong>Diagram 3: CCT Overlaps an Obstacle Significantly</strong></p> +<p>As can been seen from <strong>Diagram 3</strong>, if the CCT penetrates sufficiently that it overlaps with the shrunken shape seen by GQ, the GQ-Penetration Depth calculator will return the penetration from point c to point a. In this case, the GQ-Penetration Depth value can be used without modification in Step 4. However, as this condition would be difficult to categorize without additional computational cost, it is best to inflate the shape as recommended in Step 4 and then subtract this inflation from the returned penetration depth.</p> +<p><strong>Unified MTD Sweep</strong></p> +<p>A recent addition to the scene query sweeps is the flag PxHitFlag::eMTD. This can be used in conjunction with default sweeps to generate the MTD (Minimum Translation Direction) when an initial overlap is detected by a sweep. This flag is guaranteed to generate an appropriate normal under all circumstances, including cases where the sweep may detect an initial overlap but calling a stand-alone MTD function may report no hits. It still may suffer from accuracy issues with penetration depths but, in the cases outlined above around corners/edges, it will report a distance of 0 and the correct contact normal. This can be used to remove components of the sweep moving into the normal direction and then re-sweeping when attempting to implement a CCT. This also generates compound MTDs for meshes/heightfields, which means that it reports an MTD that de-penetrates the shape from the entire mesh rather than just an individual triangle, if such an MTD exists.</p> +</div> +<div class="section" id="quantizing-heightfield-samples"> +<h2>Quantizing HeightField Samples<a class="headerlink" href="#quantizing-heightfield-samples" title="Permalink to this headline">¶</a></h2> +<p>Heightfield samples are encoded using signed 16-bit integers for the y-height that are then converted to a float +and multiplied by PxHeightFieldGeometry::heightScale to obtain local space scaled coordinates. Shape transform is then applied on top to obtain world space location. +The transformation is performed as follows (in pseudo-code):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">localScaledVertex</span> <span class="o">=</span> <span class="n">PxVec3</span><span class="p">(</span><span class="n">row</span> <span class="o">*</span> <span class="n">desc</span><span class="p">.</span><span class="n">rowScale</span><span class="p">,</span> <span class="n">PxF32</span><span class="p">(</span><span class="n">heightSample</span><span class="p">)</span> <span class="o">*</span> <span class="n">heightScale</span><span class="p">,</span> + <span class="n">col</span> <span class="o">*</span> <span class="n">desc</span><span class="p">.</span><span class="n">columnScale</span><span class="p">)</span> +<span class="n">worldVertex</span> <span class="o">=</span> <span class="n">shapeTransform</span><span class="p">(</span> <span class="n">localScaledVertex</span> <span class="p">)</span> +</pre></div> +</div> +<p>The following code snippet shows one possible way to build quantized unscaled local space heightfield coordinates from world space grid heights stored in terrainData.verts:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxU32</span> <span class="n">ts</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// user heightfield dimensions (ts = terrain samples)</span> +<span class="c1">// create the actor for heightfield</span> +<span class="n">PxRigidStatic</span><span class="o">*</span> <span class="n">actor</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createRigidStatic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> + +<span class="c1">// iterate over source data points and find minimum and maximum heights</span> +<span class="n">PxReal</span> <span class="n">minHeight</span> <span class="o">=</span> <span class="n">PX_MAX_F32</span><span class="p">;</span> +<span class="n">PxReal</span> <span class="n">maxHeight</span> <span class="o">=</span> <span class="o">-</span><span class="n">PX_MAX_F32</span><span class="p">;</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">s</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">s</span> <span class="o"><</span> <span class="n">ts</span> <span class="o">*</span> <span class="n">ts</span><span class="p">;</span> <span class="n">s</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">minHeight</span> <span class="o">=</span> <span class="n">PxMin</span><span class="p">(</span><span class="n">minHeight</span><span class="p">,</span> <span class="n">terrainData</span><span class="p">.</span><span class="n">verts</span><span class="p">[</span><span class="n">s</span><span class="p">].</span><span class="n">y</span><span class="p">);</span> + <span class="n">maxHeight</span> <span class="o">=</span> <span class="n">PxMax</span><span class="p">(</span><span class="n">maxHeight</span><span class="p">,</span> <span class="n">terrainData</span><span class="p">.</span><span class="n">verts</span><span class="p">[</span><span class="n">s</span><span class="p">].</span><span class="n">y</span><span class="p">);</span> +<span class="p">}</span> + +<span class="c1">// compute maximum height difference</span> +<span class="n">PxReal</span> <span class="n">deltaHeight</span> <span class="o">=</span> <span class="n">maxHeight</span> <span class="o">-</span> <span class="n">minHeight</span><span class="p">;</span> + +<span class="c1">// maximum positive value that can be represented with signed 16 bit integer</span> +<span class="n">PxReal</span> <span class="n">quantization</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxReal</span><span class="p">)</span><span class="mh">0x7fff</span><span class="p">;</span> + +<span class="c1">// compute heightScale such that the forward transform will generate the closest point</span> +<span class="c1">// to the source</span> +<span class="c1">// clamp to at least PX_MIN_HEIGHTFIELD_Y_SCALE to respect the PhysX API specs</span> +<span class="n">PxReal</span> <span class="n">heightScale</span> <span class="o">=</span> <span class="n">PxMax</span><span class="p">(</span><span class="n">deltaHeight</span> <span class="o">/</span> <span class="n">quantization</span><span class="p">,</span> <span class="n">PX_MIN_HEIGHTFIELD_Y_SCALE</span><span class="p">);</span> + +<span class="n">PxU32</span><span class="o">*</span> <span class="n">hfSamples</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxU32</span><span class="p">[</span><span class="n">ts</span> <span class="o">*</span> <span class="n">ts</span><span class="p">];</span> + +<span class="n">PxU32</span> <span class="n">index</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">col</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">col</span> <span class="o"><</span> <span class="n">ts</span><span class="p">;</span> <span class="n">col</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">row</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">row</span> <span class="o"><</span> <span class="n">ts</span><span class="p">;</span> <span class="n">row</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">PxI16</span> <span class="n">height</span><span class="p">;</span> + <span class="n">height</span> <span class="o">=</span> <span class="n">PxI16</span><span class="p">(</span><span class="n">quantization</span> <span class="o">*</span> <span class="p">((</span><span class="n">terrainData</span><span class="p">.</span><span class="n">verts</span><span class="p">[(</span><span class="n">col</span><span class="o">*</span><span class="n">ts</span><span class="p">)</span> <span class="o">+</span> <span class="n">row</span><span class="p">].</span><span class="n">y</span> <span class="o">-</span> <span class="n">minHeight</span><span class="p">)</span> <span class="o">/</span> + <span class="n">deltaHeight</span><span class="p">));</span> + + <span class="n">PxHeightFieldSample</span><span class="o">&</span> <span class="n">smp</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxHeightFieldSample</span><span class="o">&</span><span class="p">)(</span><span class="n">hfSamples</span><span class="p">[(</span><span class="n">row</span><span class="o">*</span><span class="n">ts</span><span class="p">)</span> <span class="o">+</span> <span class="n">col</span><span class="p">]);</span> + <span class="n">smp</span><span class="p">.</span><span class="n">height</span> <span class="o">=</span> <span class="n">height</span><span class="p">;</span> + <span class="n">smp</span><span class="p">.</span><span class="n">materialIndex0</span> <span class="o">=</span> <span class="n">userValue0</span><span class="p">;</span> + <span class="n">smp</span><span class="p">.</span><span class="n">materialIndex1</span> <span class="o">=</span> <span class="n">userValue1</span><span class="p">;</span> + <span class="k">if</span> <span class="p">(</span><span class="n">userFlipEdge</span><span class="p">)</span> + <span class="n">smp</span><span class="p">.</span><span class="n">setTessFlag</span><span class="p">();</span> + <span class="p">}</span> +<span class="p">}</span> + +<span class="c1">// Build PxHeightFieldDesc from samples</span> +<span class="n">PxHeightFieldDesc</span> <span class="n">terrainDesc</span><span class="p">;</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">PxHeightFieldFormat</span><span class="o">::</span><span class="n">eS16_TM</span><span class="p">;</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">nbColumns</span> <span class="o">=</span> <span class="n">ts</span><span class="p">;</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">nbRows</span> <span class="o">=</span> <span class="n">ts</span><span class="p">;</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">hfSamples</span><span class="p">;</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">samples</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">PxU32</span><span class="p">);</span> <span class="c1">// 2x 8-bit material indices + 16-bit height</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">thickness</span> <span class="o">=</span> <span class="o">-</span><span class="mf">10.0f</span><span class="p">;</span> <span class="c1">// user-specified heightfield thickness</span> +<span class="n">terrainDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">=</span> <span class="n">PxHeightFieldFlags</span><span class="p">();</span> + +<span class="n">PxHeightFieldGeometry</span> <span class="n">hfGeom</span><span class="p">;</span> +<span class="n">hfGeom</span><span class="p">.</span><span class="n">columnScale</span> <span class="o">=</span> <span class="n">terrainWidth</span> <span class="o">/</span> <span class="p">(</span><span class="n">ts</span><span class="o">-</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// compute column and row scale from input terrain</span> + <span class="c1">// height grid</span> +<span class="n">hfGeom</span><span class="p">.</span><span class="n">rowScale</span> <span class="o">=</span> <span class="n">terrainWidth</span> <span class="o">/</span> <span class="p">(</span><span class="n">ts</span><span class="o">-</span><span class="mi">1</span><span class="p">);</span> +<span class="n">hfGeom</span><span class="p">.</span><span class="n">heightScale</span> <span class="o">=</span> <span class="n">deltaHeight</span><span class="o">!=</span><span class="mf">0.0f</span> <span class="o">?</span> <span class="n">heightScale</span> <span class="o">:</span> <span class="mf">1.0f</span><span class="p">;</span> +<span class="n">hfGeom</span><span class="p">.</span><span class="n">heightField</span> <span class="o">=</span> <span class="n">cooking</span><span class="p">.</span><span class="n">createHeightField</span><span class="p">(</span><span class="n">terrainDesc</span><span class="p">,</span> <span class="n">physics</span><span class="p">.</span><span class="n">getPhysicsInsertionCallback</span><span class="p">());</span> + +<span class="k">delete</span> <span class="p">[]</span> <span class="n">hfSamples</span><span class="p">;</span> + +<span class="n">PxTransform</span> <span class="n">localPose</span><span class="p">;</span> +<span class="n">localPose</span><span class="p">.</span><span class="n">p</span> <span class="o">=</span> <span class="n">PxVec3</span><span class="p">(</span><span class="o">-</span><span class="p">(</span><span class="n">terrainWidth</span> <span class="o">*</span> <span class="mf">0.5f</span><span class="p">),</span> <span class="c1">// make it so that the center of the</span> + <span class="n">minHeight</span><span class="p">,</span> <span class="o">-</span><span class="p">(</span><span class="n">terrainWidth</span> <span class="o">*</span> <span class="mf">0.5f</span><span class="p">));</span> <span class="c1">// heightfield is at world (0,minHeight,0)</span> +<span class="n">localPose</span><span class="p">.</span><span class="n">q</span> <span class="o">=</span> <span class="n">PxQuat</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">);</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">actor</span><span class="p">,</span> <span class="n">hfGeom</span><span class="p">,</span> <span class="n">material</span><span class="p">,</span> <span class="n">nbMaterials</span><span class="p">);</span> +<span class="n">shape</span><span class="o">-></span><span class="n">setLocalPose</span><span class="p">(</span><span class="n">localPose</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="reducing-memory-usage"> +<h2>Reducing memory usage<a class="headerlink" href="#reducing-memory-usage" title="Permalink to this headline">¶</a></h2> +<p>The following strategies can be used to reduce PhysX's memory usage.</p> +<div class="section" id="id1"> +<h3>Consider using tight bounds for convex meshes<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p>See the above chapter about Performance Issues for details. Using tight bounds for convex meshes is mainly useful for performance, but it can also reduce the amount of pairs coming out of the broad-phase, which decreases the amount of memory needed to manage these pairs.</p> +</div> +<div class="section" id="id2"> +<h3>Use scratch buffers<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>See the above chapter about Performance Issues for details. Scratch buffers can be shared between multiple sub-systems (e.g. physics and rendering), which can globally improve memory usage. PhysX will not use less memory per-se, but it will allocate less of it.</p> +</div> +<div class="section" id="flush-simulation-buffers"> +<h3>Flush simulation buffers<a class="headerlink" href="#flush-simulation-buffers" title="Permalink to this headline">¶</a></h3> +<p>Call the PxScene::flushSimulation function to free internal buffers used for temporary computations. But be aware that these buffers are usually allocated once and reused in subsequent frames, so releasing the memory might trigger new re-allocations during the next simulate call, which can decrease performance. Please refer to the <a class="reference internal" href="Simulation.html#simulation-memory"><em>Simulation memory</em></a> chapter for details.</p> +</div> +<div class="section" id="use-preallocation"> +<h3>Use preallocation<a class="headerlink" href="#use-preallocation" title="Permalink to this headline">¶</a></h3> +<p>Use PxSceneDesc::limits to preallocate various internal arrays. Preallocating the exact necessary size for internal buffers may use less memory overall than the usual array resizing strategy of dynamic arrays. Please refer to the <a class="reference internal" href="Simulation.html#simulation-memory"><em>Simulation memory</em></a> chapter for details.</p> +</div> +<div class="section" id="tweak-cooking-parameters"> +<h3>Tweak cooking parameters<a class="headerlink" href="#tweak-cooking-parameters" title="Permalink to this headline">¶</a></h3> +<p>Some cooking parameters have a direct impact on memory usage. In particular, PxMeshPreprocessingFlag::eDISABLE_ACTIVE_EDGES_PRECOMPUTE, PxCookingParams::suppressTriangleMeshRemapTable, PxBVH33MidphaseDesc::meshCookingHint, PxBVH33MidphaseDesc::meshSizePerformanceTradeOff, PxBVH34MidphaseDesc::numTrisPerLeaf, PxCookingParams::midphaseDesc, PxCookingParams::gaussMapLimit and PxCookingParams::buildTriangleAdjacencies can be modified to choose between runtime performance, cooking performance or memory usage.</p> +</div> +<div class="section" id="share-shape-and-mesh-data"> +<h3>Share shape and mesh data<a class="headerlink" href="#share-shape-and-mesh-data" title="Permalink to this headline">¶</a></h3> +<p>Share the same PxConvexMesh and PxTriangleMesh objects between multiple shape instances if possible. Use shared shapes if possible. Please refer to the <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollision"><em>Rigid Body Collision</em></a> chapter for details about shape sharing.</p> +</div> +<div class="section" id="id3"> +<h3>Use the scene-query and simulation flags<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3> +<p>If a shape is only used for scene-queries (raycasts, etc), disable its simulation flag. If a shape is only used for simulation (e.g. it will never be raycasted against), disable its scene-query flag. This is good for both memory usage and performance. Please refer to the <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollision"><em>Rigid Body Collision</em></a> chapter for details.</p> +</div> +</div> +<div class="section" id="behavior-issues"> +<h2>Behavior issues<a class="headerlink" href="#behavior-issues" title="Permalink to this headline">¶</a></h2> +<div class="section" id="objects-do-not-spin-realistically"> +<h3>Objects do not spin realistically<a class="headerlink" href="#objects-do-not-spin-realistically" title="Permalink to this headline">¶</a></h3> +<p>For historical reasons the default maximum angular velocity is set to a low value (7.0). This can artificially prevent the objects from spinning quickly, which may look unrealistic and wrong in some cases. Please use PxRigidDynamic::setMaxAngularVelocity to increase the maximum allowed angular velocity.</p> +</div> +<div class="section" id="overlapping-objects-explode"> +<h3>Overlapping objects explode<a class="headerlink" href="#overlapping-objects-explode" title="Permalink to this headline">¶</a></h3> +<p>Rigid bodies created in an initially overlapping state may explode, because the SDK tries to resolve the penetrations in a single time-step, which can lead to large velocities. Please use PxRigidBody::setMaxDepenetrationVelocity to limit the de-penetration velocity to a reasonable value (e.g. 3.0).</p> +</div> +<div class="section" id="rigid-bodies-are-jittering-on-the-ground"> +<h3>Rigid bodies are jittering on the ground<a class="headerlink" href="#rigid-bodies-are-jittering-on-the-ground" title="Permalink to this headline">¶</a></h3> +<p>Visualize the contacts with the visual debugger. If the jittering is caused by contacts that appear and disappear from one frame to another, try to increase the contact offset (PxShape::setContactOffset).</p> +</div> +<div class="section" id="piles-or-stacks-of-objects-are-not-going-to-sleep"> +<h3>Piles or stacks of objects are not going to sleep<a class="headerlink" href="#piles-or-stacks-of-objects-are-not-going-to-sleep" title="Permalink to this headline">¶</a></h3> +<p>PxSceneFlag::eENABLE_STABILIZATION might help here. This is not recommended for jointed objects though, so use PxRigidDynamic::setStabilizationThreshold to enable/disable this feature on a per-object basis. It should be safe to enable for objects like debris.</p> +</div> +<div class="section" id="jointed-objects-are-unstable"> +<h3>Jointed objects are unstable<a class="headerlink" href="#jointed-objects-are-unstable" title="Permalink to this headline">¶</a></h3> +<p>There are multiple things to try here:</p> +<ul class="simple"> +<li>Increase the solver iteration counts, in particular the number of position iterations. Please refer to the <a class="reference internal" href="RigidBodyDynamics.html#rigidbodydynamics"><em>Rigid Body Dynamics</em></a> chapter for details.</li> +<li>Consider creating the same constraints multiple times. This is similar to increasing the number of solver iterations, but the performance impact is localized to the jointed object rather than the simulation island it is a part of. So it can be a better option overall. Note that the order in which constraints are created is important. Say you have 4 constraints named A, B, C, D, and you want to create them 4 times each. Creating them in the AAAABBBBCCCCDDDD order will not improve the behavior, but creating them in the ABCDABCDABCDABCD order will.</li> +<li>Consider using joint projection. This might help for simple cases where only a few objects are connected. Please refer to the <a class="reference internal" href="Joints.html#joints"><em>Joints</em></a> chapter for details.</li> +<li>Use smaller time steps. This can be an effective way to improve joints' behavior, although it can be an expensive solution. Instead of running 1 simulation call with a time-step dt and N solver iterations, consider trying N simulation calls with a time-step dt/N and 1 solver iteration.</li> +<li>Consider tweaking inertia tensors. In particular, for ropes or chains of jointed objects, the PxJoint::setInvMassScale and PxJoint::setInvInertiaScale functions can be quite effective. An alternative is to compute the inertia tensor (e.g. using PxRigidBodyExt::setMassAndUpdateInertia) with an artificially increased mass, and then set the proper mass directly afterwards (using PxRigidBody::setMass).</li> +<li>Consider adding extra distance constraints. For example in a rope, it can be effective to create an extra distance constraint between the two ends of the rope, to limit its stretching. Alternatively, one can create distance constraints between elements N and N+2 in the chain.</li> +<li>Use spheres instead of capsules. A rope made of spheres will be more stable than a rope made of capsules. The positions of pivots can also affect stability. Placing the pivots at the spheres' centers is more stable than placing them on the spheres' surfaces.</li> +<li>Use articulations. Perhaps not surprisingly, articulations are much better at simulating articulated objects. They can be used to model better ropes, bridges, vehicles, or ragdolls out-of-the-box, without the need for the above workarounds. Please refer to the <a class="reference internal" href="Articulations.html#articulations"><em>Articulations</em></a> chapter for details. They are more expensive than regular joints though.</li> +</ul> +</div> +</div> +<div class="section" id="gpu-rigid-bodies"> +<h2>GPU Rigid Bodies<a class="headerlink" href="#gpu-rigid-bodies" title="Permalink to this headline">¶</a></h2> +<p>Collision detection with PxSceneFlag::eENABLE_GPU_DYNAMICS will be executed on GPU for all convex-convex, convex-box, box-box, convex-mesh, box-mesh, convex-HF anb box-HF pairs. However, such pairs will not be processed if either the vertex count of the convex hull exceeds 64 vertices (convex desc flag PxConvexFlag::eGPU_COMPATIBLE can be used to create compatible hulls), the pair requests contact modification, the triangle mesh was not cooked with GPU data requested (PxCookingParams::buildGrbData) or if the triangle mesh makes use of per-triangle materials.</p> +<p>Aggregates are used to lighten the load on broad phases. When running broad phase on the CPU, aggregates frequently improve performance by reducing the load on the core broad phase algorithm. However, there is some cost when aggregates overlap because these overlaps must be processed by a separate module. When using GPU broad phase, the use of aggregates generally result in performance regressions because the processing of aggregate overlaps occurs on the CPU and, while using aggregates can reduce the load on the GPU broad phase, the amount by which they improve GPU broad phase performance is frequently smaller than the cost of processing the aggregate overlaps.</p> +</div> +<div class="section" id="determinism"> +<h2>Determinism<a class="headerlink" href="#determinism" title="Permalink to this headline">¶</a></h2> +<p>The PhysX SDK can be described as offering limited determinism. Results can vary between platforms due to differences in hardware maths precision and differences in how the compiler reoders instructions during optimization. This means that behavior can be different between different platforms, different compilers operating on the same platform or between optimized and unoptimized builds using the same compiler on the same platform. However, on a given platform, given the exact same sequence of events operating on the exact scene using a consistent time-stepping scheme, PhysX is expected to produce deterministic results. In order to achieve this determinism, the application must recreate the scene in the exact same order each time and insert the actors into a newly-created PxScene. There are several other factors that can affect determinism so if an inconsistent (e.g. variable) time-stepping scheme is used or if the application does not perform the same sequence of API calls on the same frames, the PhysX simulation can diverge.</p> +<p>In addition, the PhysX simulation can produce divergent behavior if any conditions in the simulation has varied. Even the addition of a single actor that is not interacting with the existing set of actors in the scene can produce divergent results.</p> +<p>PhysX provides a mechanism to overcome the issue of divergent behavior in existing configurations as a result of additional actors being added or actors being removed from the scene that do not interact with the other actors in the scene. This mechanism can be enabled by raising PxSceneFlag::eENABLE_ENHANCED_DETERMINISM on PxSceneDesc::flags prior to creating the scene. Enabling this mode makes some performance concessions to be able to offer an improved level of determinism. The application must still follow all the requirements to achieve deterministic behavior described previously in order for this mechanism to produce consistent results.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Best Practices Guide</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#debugging">Debugging</a><ul> +<li><a class="reference internal" href="#use-checked-builds-and-the-error-stream">Use checked builds and the error stream</a></li> +<li><a class="reference internal" href="#visualizing-physics-data">Visualizing physics data</a></li> +<li><a class="reference internal" href="#visualizing-physics-data-2">Visualizing physics data (2)</a></li> +<li><a class="reference internal" href="#limiting-coordinates">Limiting coordinates</a></li> +</ul> +</li> +<li><a class="reference internal" href="#performance-issues">Performance Issues</a><ul> +<li><a class="reference internal" href="#use-profile-builds-to-identify-performance-bottlenecks">Use profile builds to identify performance bottlenecks</a></li> +<li><a class="reference internal" href="#use-release-builds-for-final-performance-tests">Use release builds for final performance tests</a></li> +<li><a class="reference internal" href="#disable-debug-visualization-in-final-release-builds">Disable debug visualization in final/release builds</a></li> +<li><a class="reference internal" href="#debug-visualization-is-very-slow">Debug visualization is very slow</a></li> +<li><a class="reference internal" href="#consider-using-tight-bounds-for-convex-meshes">Consider using tight bounds for convex meshes</a></li> +<li><a class="reference internal" href="#use-scratch-buffers">Use scratch buffers</a></li> +<li><a class="reference internal" href="#use-the-proper-mid-phase-algorithm">Use the proper mid-phase algorithm</a></li> +<li><a class="reference internal" href="#use-the-proper-narrow-phase-algorithm">Use the proper narrow-phase algorithm</a></li> +<li><a class="reference internal" href="#use-the-proper-broad-phase-algorithm">Use the proper broad-phase algorithm</a></li> +<li><a class="reference internal" href="#use-the-scene-query-and-simulation-flags">Use the scene-query and simulation flags</a></li> +<li><a class="reference internal" href="#tweak-the-dynamic-tree-rebuild-rate">Tweak the dynamic tree rebuild rate</a></li> +<li><a class="reference internal" href="#use-the-insertion-callback-when-cooking-at-runtime">Use the insertion callback when cooking at runtime</a></li> +<li><a class="reference internal" href="#the-well-of-despair">The "Well of Despair"</a></li> +<li><a class="reference internal" href="#pruner-performance-for-streamed-environments">Pruner Performance for Streamed Environments</a></li> +<li><a class="reference internal" href="#performance-implications-for-multi-threading">Performance Implications for Multi-Threading</a></li> +<li><a class="reference internal" href="#memory-allocation">Memory allocation</a></li> +</ul> +</li> +<li><a class="reference internal" href="#character-controller-systems-using-scene-queries-and-penetration-depth-computation">Character Controller Systems using Scene Queries and Penetration Depth Computation</a></li> +<li><a class="reference internal" href="#quantizing-heightfield-samples">Quantizing HeightField Samples</a></li> +<li><a class="reference internal" href="#reducing-memory-usage">Reducing memory usage</a><ul> +<li><a class="reference internal" href="#id1">Consider using tight bounds for convex meshes</a></li> +<li><a class="reference internal" href="#id2">Use scratch buffers</a></li> +<li><a class="reference internal" href="#flush-simulation-buffers">Flush simulation buffers</a></li> +<li><a class="reference internal" href="#use-preallocation">Use preallocation</a></li> +<li><a class="reference internal" href="#tweak-cooking-parameters">Tweak cooking parameters</a></li> +<li><a class="reference internal" href="#share-shape-and-mesh-data">Share shape and mesh data</a></li> +<li><a class="reference internal" href="#id3">Use the scene-query and simulation flags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#behavior-issues">Behavior issues</a><ul> +<li><a class="reference internal" href="#objects-do-not-spin-realistically">Objects do not spin realistically</a></li> +<li><a class="reference internal" href="#overlapping-objects-explode">Overlapping objects explode</a></li> +<li><a class="reference internal" href="#rigid-bodies-are-jittering-on-the-ground">Rigid bodies are jittering on the ground</a></li> +<li><a class="reference internal" href="#piles-or-stacks-of-objects-are-not-going-to-sleep">Piles or stacks of objects are not going to sleep</a></li> +<li><a class="reference internal" href="#jointed-objects-are-unstable">Jointed objects are unstable</a></li> +</ul> +</li> +<li><a class="reference internal" href="#gpu-rigid-bodies">GPU Rigid Bodies</a></li> +<li><a class="reference internal" href="#determinism">Determinism</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ExtendingSerialization.html" + title="previous chapter">Extending Serialization</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="MigrationFrom28.html" + title="next chapter">Migrating From PhysX SDK 2.x to 3.x</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" /> + <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="MigrationFrom28.html" title="Migrating From PhysX SDK 2.x to 3.x" + >next</a></li> + <li class="right" > + <a href="ExtendingSerialization.html" title="Extending Serialization" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/BuildingWithPhysX.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/BuildingWithPhysX.html new file mode 100644 index 00000000..1563e025 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/BuildingWithPhysX.html @@ -0,0 +1,178 @@ +<!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>Building with PhysX — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="The PhysX API" href="API.html" /> + <link rel="prev" title="Snippets" href="HelloWorld.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="API.html" title="The PhysX API" + accesskey="N">next</a></li> + <li class="right" > + <a href="HelloWorld.html" title="Snippets" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="building-with-physx"> +<span id="id1"></span><h1>Building with PhysX<a class="headerlink" href="#building-with-physx" title="Permalink to this headline">¶</a></h1> +<p>On Windows, PhysX requires either Visual Studio 2010 or Visual Studio 2012.</p> +<div class="section" id="build-settings"> +<h2>Build Settings<a class="headerlink" href="#build-settings" title="Permalink to this headline">¶</a></h2> +<p>The PhysX headers should compile cleanly at the highest typical warning levels (/W4 for Visual Studio, -Wall -Wextra -pedantic for gcc- and clang-based compilers.) Stricter warning settings may result in a small number of benign informational warnins.</p> +<p>The PhysX source projects and snippets will compile cleanly using the project files or makefiles supplied.</p> +</div> +<div class="section" id="build-configurations"> +<h2>Build Configurations<a class="headerlink" href="#build-configurations" title="Permalink to this headline">¶</a></h2> +<p>The SDK has four build configurations available, designed for different stages of development and deployment.</p> +<ul class="simple"> +<li>the <em>debug</em> build can be useful for error analysis, but contains asserts used for SDK development which some customers may find too intrusive for daily use. Optimizations are turned off for this configuration.</li> +<li>the <em>checked</em> build contains code to detect invalid parameters, API race conditions, and other incorrect uses of the API which might otherwise cause mysterious crashes or failures in simulation.</li> +<li>the <em>profile</em> build omits the checks, but still has PVD and memory instrumentation.</li> +<li>the <em>release</em> build is built for minimal footprint and maximum speed. It omits most checks and instrumentation.</li> +</ul> +<p>Simulation works the same way in all of them, and all are compiled with high optimization levels (except debug configuration).</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">We strongly recommend that you use the checked build as the primary configuration for day-to-day development and QA.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">PhysX libraries of different build configurations (e.g. the DEBUG version of PhysXVehicle and the CHECKED version of PhysXVisualDebuggerSDK) should never be mixed in an application because this will result a CRT conflict.</p> +</div> +</div> +<div class="section" id="header-files"> +<span id="id2"></span><h2>Header Files<a class="headerlink" href="#header-files" title="Permalink to this headline">¶</a></h2> +<p>To build your own PhysX app, you will need to add some include paths and libraries to your project makefile or IDE.</p> +<p>Users should specify the root "Include" and "Lib" folders in the additional include, and library directories respectively. There is a combined include header available as:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "PxPhysicsAPI.h"</span> +</pre></div> +</div> +<p>This will include the entire PhysX API including core, extensions, vehicles, etc. It is also possible to include subsets of the SDK if preferred, for example:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "vehicle/PxVehicleSDK.h"</span> +</pre></div> +</div> +</div> +<div class="section" id="libraries"> +<span id="id3"></span><h2>Libraries<a class="headerlink" href="#libraries" title="Permalink to this headline">¶</a></h2> +<p>At a minimum, applications need to link against the following libraries with the appropriate platform extension (e.g. ".lib" or ".a") and with * being a x86 or x64 for Windows platforms:</p> +<ul class="simple"> +<li>PhysX3_*.lib</li> +<li>PhysX3Common_*.lib</li> +<li>PxFoundation_*.lib</li> +</ul> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The static libraries we provide with the Windows binary distribution are linked against the Multi-Threaded static C Run-Time (CRT) libraries. This means that your application must also use the same CRT flavor. If you need to use a different CRT version, you must upgrade to our source license. The source distribution can simply be recompiled using different CRT settings.</p> +</div> +</div> +<div class="section" id="redistribution"> +<span id="id4"></span><h2>Redistribution<a class="headerlink" href="#redistribution" title="Permalink to this headline">¶</a></h2> +<p>On the Windows platform, you need to redistribute some of our DLLs to end users as part of your application:</p> +<ul class="simple"> +<li>PhysX3Common_*.dll - will always be needed.</li> +<li>PhysX3_*.dll - will always be needed.</li> +<li>PxFoundation_*.dll - will always be needed.</li> +<li>PhysX3Cooking_*.dll - you only need to bundle if your application cooks geometry data on the fly.</li> +<li>PhysX3GPU_*.dll - is only needed if your application runs some simulation on the GPU.</li> +<li>PhysX3CharacterKinematic_*.dll - is only needed if your application uses the character controller.</li> +<li>PxPvdSDK_*.dll - is only needed if your application uses PVD.</li> +</ul> +<p>Where * is a platform specific suffix, e.g. x86 or x64. You will need one or the other depending on whether your application is built in 64 bit mode.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Building with PhysX</a><ul> +<li><a class="reference internal" href="#build-settings">Build Settings</a></li> +<li><a class="reference internal" href="#build-configurations">Build Configurations</a></li> +<li><a class="reference internal" href="#header-files">Header Files</a></li> +<li><a class="reference internal" href="#libraries">Libraries</a></li> +<li><a class="reference internal" href="#redistribution">Redistribution</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="HelloWorld.html" + title="previous chapter">Snippets</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="API.html" + title="next chapter">The PhysX API</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" /> + <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="API.html" title="The PhysX API" + >next</a></li> + <li class="right" > + <a href="HelloWorld.html" title="Snippets" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/CharacterControllers.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/CharacterControllers.html new file mode 100644 index 00000000..9e2d14f4 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/CharacterControllers.html @@ -0,0 +1,475 @@ +<!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>Character Controllers — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Particles (deprecated)" href="Particles.html" /> + <link rel="prev" title="Vehicles" href="Vehicles.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Particles.html" title="Particles (deprecated)" + accesskey="N">next</a></li> + <li class="right" > + <a href="Vehicles.html" title="Vehicles" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="character-controllers"> +<span id="character"></span><h1>Character Controllers<a class="headerlink" href="#character-controllers" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>The character controller (CCT) SDK is an external component built on top of the PhysX SDK, in a manner similar to PhysXExtensions.</p> +<p>CCTs can be implemented in a number of ways: the PhysX implementation in the CCT module is only one of them.</p> +<p>By nature, CCTs are often very game-specific, and they can have a number of unique features in each game. For example the character's bounding volume may be a capsule in one game, and an inverted pyramid in another. The CCT SDK does not attempt to provide a one-size-fits-all solution that would work out-of-the-box for all possible games. But it provides the basic features common to all CCTs: character control and character interactions. It is a default starting point for users, a strong base that one can build on, and later modify or customize if needed.</p> +</div> +<div class="section" id="kinematic-character-controller"> +<h2>Kinematic Character Controller<a class="headerlink" href="#kinematic-character-controller" title="Permalink to this headline">¶</a></h2> +<p>The PhysX CCT is a kinematic controller. Traditionally, character controllers can be either kinematic or dynamic. A kinematic controller directly works with input displacement vectors (1st order control). A dynamic controller works with input velocities (2nd order control) or forces (3rd order control).</p> +<p>In the past, games did not use a 'real' physics engine like the PhysX SDK. But they still used a character controller to move a player in a level. These games, such as Quake or even Doom, had a dedicated, customized piece of code to implement collision detection and response, which was often the only piece of physics in the whole game. It actually had little physics, but a lot of carefully tweaked values to provide a good feeling while controlling the player. The particular behavior it implemented is often called the 'collide and slide' algorithm, and it has been 'tweaked for more than a decade'. The PhysX CCT module is an implementation of such an algorithm, providing a robust and well-known behavior for character control.</p> +<p>The main advantage of kinematic controllers is that they do not suffer from the following issues, which are typical for dynamic controllers:</p> +<ul> +<li><p class="first">(lack of) continuous collision detection: typical physics engines use discrete collision checks, leading to the notorious 'tunneling effect' that has plagued various commercial & non-commercial physics packages for years. This leads to three main problems:</p> +<blockquote> +<div><ul class="simple"> +<li>the tunneling effect itself : if the character goes too fast it might tunnel through a wall</li> +<li>as a consequence, the character's maximum velocity be limited (thus also limiting the game play possibilities)</li> +<li>even if it does not tunnel, the character might jitter when pushed forward in a corner for example, because the physics engine keeps moving it back and forth to slightly different positions.</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">No direct control: a rigid body is typically controlled with impulses or forces. It is usually not possible to move it directly to its final position: instead one must convert the delta position vector to impulses/forces, apply them, and hope that the character will end up at the desired position. This does not always work well, in particular when the physics engine uses an imperfect linear solver.</p> +</li> +<li><p class="first">Trouble with friction: when the character is standing on a ramp, it should not slide. So infinite friction is needed here. When the character is moving forward on that same ramp, it should not slow down. One does not need any friction here. Similarly, when the character is sliding against a wall, it should not slow down either. Thus, for a CCT, friction is usually either 0 or infinite. Unfortunately the friction model in a physics engine might not be perfect, and it is easy to end up with either a small amount of friction (the character slows down a tiny bit) or a very-large-but-not-infinite friction (the character slides very slowly on that ramp no matter how artificially big the friction parameters are). The conflicting requirements for ramps also mean that usually there is simply no way to perfectly model desired behavior.</p> +</li> +<li><p class="first">Trouble with restitution: typically, restitution should be avoided for CCTs. When the character moves fast and collides with a wall, it should not bounce away from it. When the character falls from a height and lands on the ground, flexing his legs, any bounce should be prevented. But once again, even when the restitution is exactly zero, a physics engine can nonetheless make the CCTs bounce a bit. This is not only related to the imperfect nature of the linear solver, it also has to do with how typical penetration-depth-based engines recover from overlap situations, sometimes applying excessive forces that separate the objects too much.</p> +</li> +<li><p class="first">Undesired jumps: characters must often stick to the ground, no matter what the physical behavior should be. For example characters in action games tend to move fast, at unrealistic speeds. When they reach the top of a ramp, the physics engine often makes them jump a bit, in the same way a fast car would jump in the streets of San Francisco. But that is often not the desired behavior: instead the character should often stick to the ground regardless of its current velocity. This is sometimes implemented using fixed joints, but this is an unnecessarily complex solution to a problem that is easily prevented with kinematic controllers.</p> +</li> +<li><p class="first">Undesired rotations: a typical character is always standing up and never rotating. However physics engines often have poor support for that sort of constraints, and a great deal of effort is often put into preventing a capsule around the character from falling (it should always stands up on its tip). This is often implemented using artificial joints, and the resulting system is neither very robust nor very fast.</p> +</li> +</ul> +<p>To summarize, a lot of effort can be spent on tweaking and disabling the physics engine's features simply to emulate what is otherwise a much less complex piece of custom code. It is natural to instead keep using that simple piece of custom code.</p> +</div> +<div class="section" id="creating-a-character-controller"> +<h2>Creating a character controller<a class="headerlink" href="#creating-a-character-controller" title="Permalink to this headline">¶</a></h2> +<p>First, create a controller manager somewhere in your application. This object keeps track of all created controllers and allows characters from the same manager to interact with each other. Create the manager using the <em>PxCreateControllerManager</em> function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> <span class="c1">// Previously created scene</span> +<span class="n">PxControllerManager</span><span class="o">*</span> <span class="n">manager</span> <span class="o">=</span> <span class="n">PxCreateControllerManager</span><span class="p">(</span><span class="o">*</span><span class="n">scene</span><span class="p">);</span> +</pre></div> +</div> +<p>Then, create one controller for each character in the game. At the time of writing only boxes (<em>PxBoxController</em>) and capsules (<em>PxCapsuleController</em>) are supported. A capsule controller for example, is created this way:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxCapsuleControllerDesc</span> <span class="n">desc</span><span class="p">;</span> +<span class="p">...</span> +<span class="o"><</span><span class="n">fill</span> <span class="n">the</span> <span class="n">descriptor</span> <span class="n">here</span><span class="o">></span> +<span class="p">...</span> +<span class="n">PxController</span><span class="o">*</span> <span class="n">c</span> <span class="o">=</span> <span class="n">manager</span><span class="o">-></span><span class="n">createController</span><span class="p">(</span><span class="n">desc</span><span class="p">);</span> +</pre></div> +</div> +<p>The manager class will keep track of all created controllers. They can be retrieved at any time using the following functions:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">getNbControllers</span><span class="p">()</span> <span class="k">const</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="n">PxController</span><span class="o">*</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">getController</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">index</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>To release a character controller, simply call its release function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxController</span><span class="o">::</span><span class="n">release</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>To release all created character controllers at once, either release the manager object itself, or use the following function if you intend to keep using the manager:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">purgeControllers</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>The creation of a controller manager and its subsequent controllers is illustrated in SampleBridges.</p> +</div> +<div class="section" id="overlap-recovery-module"> +<h2>Overlap Recovery Module<a class="headerlink" href="#overlap-recovery-module" title="Permalink to this headline">¶</a></h2> +<p>Ideally, character should not be created in an initial overlap state, i.e. they should be created in a position where they do not overlap the surrounding geometry. The various PxScene overlap functions can be used to check the desired volume of space is empty, prior to creating the character. By default the CCT module does not check for overlaps itself, and creating a character that initially overlaps the world's static geometry can have undesired and undefined behavior - like the character going through the ground for example.</p> +<p>However, the overlap recovery module can be used to automatically correct the character's initial position. As long as the amount of overlap is reasonable, the recovery module should be able to relocate the character to a proper, collision-free position.</p> +<p>The overlap recovery module can be useful in several other situations. There are three main cases:</p> +<ul class="simple"> +<li>when the CCT is directly spawned or teleported in another object</li> +<li>when the CCT algorithm fails due to limited FPU accuracy</li> +<li>when the "up vector" is modified, making the rotated CCT shape overlap surrounding objects</li> +</ul> +<p>When activated, the CCT module will automatically try to resolve the penetration, and move the CCT to a safe place where it does not overlap other objects anymore. This only concerns static objects, dynamic objects are ignored by this module.</p> +<p>Enable or disable the overlap recovery module with this function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">setOverlapRecoveryModule</span><span class="p">(</span><span class="kt">bool</span> <span class="n">flag</span><span class="p">);</span> +</pre></div> +</div> +<p>By default the character controllers use precise sweep tests, whose accuracy is usually enough to avoid all penetration - provided the contact offset is not too small. Thus, in most cases the overlap recovery module is not needed. When it is used though, the sweep tests can be switched to less accurate but potentially faster versions, using the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">setPreciseSweeps</span><span class="p">(</span><span class="kt">bool</span> <span class="n">flag</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="character-volume"> +<h2>Character Volume<a class="headerlink" href="#character-volume" title="Permalink to this headline">¶</a></h2> +<p>The character uses a bounding volume that is independent from already existing shapes in the SDK. We currently support two different shapes around the character:</p> +<ul class="simple"> +<li>An AABB, defined by a center position and an extents vector. The AABB does not rotate. It always has a fixed rotation even when the player is (visually) rotating. This avoids getting stuck in places too tight to let the AABB rotate.</li> +<li>A capsule, defined by a center position, a vertical height and a radius. The height is the distance between the two sphere centers at the end of the capsule. The capsule has a better behavior when climbing stairs, for example. It is the recommended default choice.</li> +</ul> +<img alt="../_images/cctCapsule.png" src="../_images/cctCapsule.png" /> +<p>Note: versions prior to 2.3 also supported a sphere. This has been removed since the PxCapsuleController is more robust and provides the same functionality (zero length capsule).</p> +<p>A small skin is maintained around the character's volume, to avoid numerical issues that would otherwise happen when the character touches other shapes. The size of this skin is user-defined. When rendering the character's volume for debug purpose, remember to expand the volume by the size of this skin to get accurate debug visualization. This skin is defined in <em>PxControllerDesc::contactOffset</em> and later available through the <em>PxController::getContactOffset()</em> function.</p> +</div> +<div class="section" id="volume-update"> +<h2>Volume Update<a class="headerlink" href="#volume-update" title="Permalink to this headline">¶</a></h2> +<p>Sometimes it is useful to change the size of the character's volume at runtime. For example if the character can crouch, it might be required to reduce the height of its bounding volume so that it can then move to places he could not reach otherwise.</p> +<p>For the box controller, the related functions are:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">PxBoxController</span><span class="o">::</span><span class="n">setHalfHeight</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">halfHeight</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">PxBoxController</span><span class="o">::</span><span class="n">setHalfSideExtent</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">halfSideExtent</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">PxBoxController</span><span class="o">::</span><span class="n">setHalfForwardExtent</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">halfForwardExtent</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>And for the capsule controller:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">PxCapsuleController</span><span class="o">::</span><span class="n">setRadius</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">radius</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">PxCapsuleController</span><span class="o">::</span><span class="n">setHeight</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">height</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>Changing the size of a controller using the above functions does not actually change its position. So if the character is standing on the ground (touching it), and its height is suddenly reduced without updating its position, the character will end up levitating above the ground for a few frames until gravity makes it fall and touch the ground again. This happens because the controllers positions are located at the center of the shapes, rather than the bottom. Thus, to modify a controller's height and preserve its bottom position, one must change both the height and position of a controller. The following helper function does that automatically:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxController</span><span class="o">::</span><span class="n">resize</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">height</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<img alt="../_images/cctResize.png" src="../_images/cctResize.png" /> +<p>It is important to note that volumes are directly modified without any extra tests, and thus it might happen that the resulting volume overlaps some geometry nearby. For example when resizing the character to leave a crouch pose, i.e. when the size of the character is <em>increased</em>, it is important to first check that the character can indeed 'stand up': the volume of space above the character must be empty (collision free). It is recommended to use the various PxScene overlap queries for this purpose:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">PxScene</span><span class="o">::</span><span class="n">overlap</span><span class="p">(...)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>Updating the character's volume at runtime to implement a 'crouch' motion is illustrated in SampleNorthPole. Using overlap queries to leave the crouch pose is done in the <em>SampleNorthPole::tryStandup()</em> function.</p> +</div> +<div class="section" id="moving-a-character-controller"> +<h2>Moving a Character Controller<a class="headerlink" href="#moving-a-character-controller" title="Permalink to this headline">¶</a></h2> +<p>The heart of the CCT algorithm is the function that actually moves characters around:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxControllerCollisionFlags</span> <span class="n">collisionFlags</span> <span class="o">=</span> + <span class="n">PxController</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">disp</span><span class="p">,</span> <span class="n">PxF32</span> <span class="n">minDist</span><span class="p">,</span> <span class="n">PxF32</span> <span class="n">elapsedTime</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxControllerFilters</span><span class="o">&</span> <span class="n">filters</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxObstacleContext</span><span class="o">*</span> <span class="n">obstacles</span><span class="o">=</span><span class="nb">NULL</span><span class="p">);</span> +</pre></div> +</div> +<p><em>disp</em> is the displacement vector for current frame. It is typically a combination of vertical motion due to gravity and lateral motion when your character is moving. Note that users are responsible for applying gravity to characters here.</p> +<p><em>minDist</em> is a minimal length used to stop the recursive displacement algorithm early when remaining distance to travel goes below this limit.</p> +<p><em>elapsedTime</em> is the amount of time that passed since the last call to the move function.</p> +<p><em>filters</em> are filtering parameters similar to the ones used in the SDK. Use these to control what the character should collide with.</p> +<p><em>obstacles</em> are optional additional obstacle objects with which the character should collide. Those objects are fully controlled by users and do not need to have counterpart SDK objects. Note that touched obstacles are cached, meaning that the cache needs to be invalidated if the collection of obstacles changes.</p> +<p><em>collisionFlags</em> is a bit mask returned to users to define collision events that happened during the move. This is a combination of PxControllerCollisionFlag flags. It can be used to trigger various character animations. For example your character might be falling while playing a falling idle animation, and you might start the land animation as soon as PxControllerCollisionFlag::eCOLLISION_DOWN is returned.</p> +<p>It is important to understand the difference between <em>PxController::move</em> and <em>PxController::setPosition</em>. The <em>PxController::move</em> function is the core of the CCT module. This is where the aforementioned 'collide-and-slide' algorithm takes place. So the function will start from the CCT's current position, and use sweep tests to attempt to move in the required direction. If obstacles are found, it may make the CCT slide smoothly against them. Or the CCT can get blocked against a wall: the result of the move call depends on the surrounding geometry. On the contrary, <em>PxController::setPosition</em> is a simple 'teleport' function that will move the CCT to desired position no matter what, regardless of where the CCT starts from, regardless of surrounding geometry, and even if the required position is in the middle of another object.</p> +<p>Both <em>PxController::move</em> and <em>PxController::setPosition</em> are demonstrated in SampleBridges.</p> +</div> +<div class="section" id="graphics-update"> +<h2>Graphics Update<a class="headerlink" href="#graphics-update" title="Permalink to this headline">¶</a></h2> +<p>Each frame, after <em>PxController::move</em> calls, graphics object must be kept in sync with the new CCT positions. Controllers' positions can be accessed using:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxExtendedVec3</span><span class="o">&</span> <span class="n">PxController</span><span class="o">::</span><span class="n">getPosition</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> +</pre></div> +</div> +<p>This function returns the position from the center of the collision shape, since this is what is used internally both within the PhysX SDK and by usual graphics APIs. Retrieving this position and passing it to the renderer is illustrated in SampleBridges. Note that the position uses double-precision, to make the CCT module work well with large worlds. Also note that a controller never rotates so you can only access its position.</p> +<p>Alternative helper functions are provided to work using the character's bottom position, a.k.a. the foot position:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxExtendedVec3</span><span class="o">&</span> <span class="n">PxController</span><span class="o">::</span><span class="n">getFootPosition</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">PxController</span><span class="o">::</span><span class="n">setFootPosition</span><span class="p">(</span><span class="k">const</span> <span class="n">PxExtendedVec3</span><span class="o">&</span> <span class="n">position</span><span class="p">);</span> +</pre></div> +</div> +<p>Note that the foot position takes the contact offset into account.</p> +<img alt="../_images/cctContactOffset.png" src="../_images/cctContactOffset.png" /> +</div> +<div class="section" id="auto-stepping"> +<h2>Auto Stepping<a class="headerlink" href="#auto-stepping" title="Permalink to this headline">¶</a></h2> +<p>Without auto-stepping it is easy for a box-controlled character to get stuck against slight elevations of the ground mesh. In the following picture the small step would stop the character completely. It feels unnatural because in the real world a character would just cross this small obstacle without thinking about it.</p> +<img alt="../_images/cctStepOffset0.png" src="../_images/cctStepOffset0.png" /> +<p>This is what auto-stepping enables us to do. Without any intervention from the player (i.e. without them thinking about it) the box correctly steps above the minor obstacle.</p> +<img alt="../_images/cctStepOffset1.png" src="../_images/cctStepOffset1.png" /> +<p>However, if the obstacle is too big, i.e. its height is greater than the <em>stepOffset</em> parameter, the controller cannot climb automatically, and the character gets stuck (correctly this time):</p> +<img alt="../_images/cctStepOffset2.png" src="../_images/cctStepOffset2.png" /> +<p>'Climbing' (over this bigger obstacle, for example) may also be implemented in the future, as an extension of auto-stepping. The step offset is defined in <em>PxControllerDesc::stepOffset</em> and later available through the <em>PxController::getStepOffset()</em> function.</p> +<p>Generally speaking, the step offset should be kept as small as possible.</p> +</div> +<div class="section" id="climbing-mode"> +<h2>Climbing Mode<a class="headerlink" href="#climbing-mode" title="Permalink to this headline">¶</a></h2> +<p>The auto-stepping feature was originally intended for box controllers, which are easily blocked by small obstacles on the ground. Capsule controllers, thanks to their rounded nature, do not necessarily need the feature.</p> +<p>Even with a step offset of 0.0, capsules are able to go over small obstacles since their rounded bottom produces an upward motion after colliding with a small obstacle.</p> +<p>Capsules with a non-zero step-offset can go over obstacles higher than the step offset, because of the combined effect of the auto-stepping feature and their rounded shape. In this case the largest altitude a capsule can climb over is difficult to predict, as it depends on the auto-step value, the capsule's radius, and even the magnitude of the displacement vector.</p> +<p>This is why there are two different climbing modes for capsules:</p> +<ul class="simple"> +<li><em>PxCapsuleClimbingMode::eEASY</em>: in this mode, capsules are not constrained by the step offset value. They can potentially climb over obstacles higher than this value.</li> +<li><em>PxCapsuleClimbingMode::eCONSTRAINED</em>: in this mode, an attempt is made to make sure the capsule can not climb over obstacles higher than the step offset.</li> +</ul> +</div> +<div class="section" id="up-vector"> +<h2>Up Vector<a class="headerlink" href="#up-vector" title="Permalink to this headline">¶</a></h2> +<p>In order to implement the auto-stepping feature, the SDK needs to know about the 'up' vector. The up vector is defined in <em>PxControllerDesc::upDirection</em> and later available through the <em>PxController::getUpDirection()</em> function.</p> +<p>The up vector does not need to be axis-aligned. It can be arbitrary, modified each frame using the <em>PxController::setUpDirection()</em> function, allowing the character to navigate on spherical worlds. This is demonstrated in SampleCustomGravity.</p> +<p>Modifying the up vector changes the way the CCT library sees character volumes. For example a capsule is defined by a <em>PxCapsuleControllerDesc::height</em>, which is the 'vertical height' along the up vector. Thus, changing the up vector effectively rotates the capsule from the point of view of the library. +The modification happens immediately, without tests to validate that the character does not overlap nearby geometry. It is then possible for the character to be penetrating some geometry right after the call. Using the overlap recovery module is recommended to solve these issues.</p> +<img alt="../_images/cctUpVector.png" src="../_images/cctUpVector.png" /> +<p>In the above picture the capsule on the left uses a vertical up vector and does not collide with the surrounding geometry. On the right the up vector has been set to 45 degrees, and the capsule now penetrates the wall nearby. For most applications the up vector will be constant, and the same for all characters. These issues will only appear for characters navigating in spherical worlds (e.g. planetoids, etc).</p> +</div> +<div class="section" id="walkable-parts-invisible-walls"> +<h2>Walkable Parts & Invisible Walls<a class="headerlink" href="#walkable-parts-invisible-walls" title="Permalink to this headline">¶</a></h2> +<p>By default the characters can move everywhere. This may not always be a good thing. In particular, it is often desired to prevent walking on polygons whose slope is steep. The SDK can do this automatically thanks to a user-defined slope limit. All polygons whose slope is higher than the limit slope will be marked as non walk-able, and the SDK will not let characters go there.</p> +<p>Two modes are available to define what happens when touching a non walk-able part. The desired mode is selected with the <em>PxControllerDesc::nonWalkableMode</em> enum:</p> +<ul class="simple"> +<li><em>PxControllerNonWalkableMode::ePREVENT_CLIMBING</em> prevents the character from moving up a slope, but does not move the character otherwise. The character will still be able to walk laterally on these polygons, and to move down their slope.</li> +<li><em>PxControllerNonWalkableMode::ePREVENT_CLIMBING_AND_FORCE_SLIDING</em> not only prevents the character from moving up non walk-able slopes but also forces it to slide down those slopes.</li> +</ul> +<p>The slope limit is defined in <em>PxControllerDesc::slopeLimit</em> and later available through the <em>PxController::getSlopeLimit()</em> function. The limit is expressed as the cosine of desired limit angle. For example this uses a slope limit of 45 degrees:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">slopeLimit</span> <span class="o">=</span> <span class="n">cosf</span><span class="p">(</span><span class="n">PxMath</span><span class="o">::</span><span class="n">degToRad</span><span class="p">(</span><span class="mf">45.0f</span><span class="p">));</span> +</pre></div> +</div> +<p>Using slopeLimit = 0.0f automatically disables the feature (i.e. characters can go everywhere).</p> +<p>This feature is not always needed. A common strategy is to disable it and place invisible walls in the level, to restrict player's movements. The character module can also create those walls for you, if <em>PxControllerDesc::invisibleWallHeight</em> is non-zero. In this case the library creates those extra triangles on the fly, and that parameter controls their height (extruded in the user-defined up direction). A common problem is that those invisible walls are only created when non-walkable triangles are found. It is possible for a jumping character to go over them, if its bounding volume is too small and does not collide with the non-walkable triangles below him. The <em>PxControllerDesc::maxJumpHeight</em> parameter addresses this issue, by extending the size of the bounding volume downward. That way all potentially non-walkable triangles are properly returned by the collision queries, and invisible walls are properly created - preventing the character from jumping on them.</p> +<p>A known limitation is that the slope limit mechanism is currently only enabled against static objects. It is not enabled against dynamic objects, and in particular against kinematic objects. It is also not supported for static spheres or static capsules.</p> +</div> +<div class="section" id="obstacle-objects"> +<h2>Obstacle Objects<a class="headerlink" href="#obstacle-objects" title="Permalink to this headline">¶</a></h2> +<p>Sometimes it is convenient to create additional obstacles for the CCT to collide with, without creating an actual SDK object. This is useful in a number of situations. For example:</p> +<ul class="simple"> +<li>the obstacles might only exist for a couple of frames, in which case creating and deleting SDK objects is not always efficient.</li> +<li>the obstacles might only exist for stopping the characters, not the SDK's dynamic objects. This would be for example invisible walls around geometry, that only the characters should collide with. In this case it may not be very efficient to create the invisible walls as SDK objects, since their interactions would then have to be filtered out for everything except the characters. It is probably more efficient to create those additional invisible walls as external obstacles, that only characters can interact with.</li> +<li>the obstacles might be dynamic and updated with a variable timestep, while the SDK uses a fixed timestep. This could be for example a moving platform on which the characters can stand.</li> +</ul> +<p>At the time of writing the character controller supports box and capsule <em>PxObstacle</em> objects, namely <em>PxBoxObstacle</em> and <em>PxCapsuleObstacle</em>. To create those, first create a <em>PxObstacleContext</em> object using the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxObstacleContext</span><span class="o">*</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">createObstacleContext</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>Then manage obstacles with:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">ObstacleHandle</span> <span class="n">PxObstacleContext</span><span class="o">::</span><span class="n">addObstacle</span><span class="p">(</span><span class="k">const</span> <span class="n">PxObstacle</span><span class="o">&</span> <span class="n">obstacle</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">PxObstacleContext</span><span class="o">::</span><span class="n">removeObstacle</span><span class="p">(</span><span class="n">ObstacleHandle</span> <span class="n">handle</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">PxObstacleContext</span><span class="o">::</span><span class="n">updateObstacle</span><span class="p">(</span><span class="n">ObstacleHandle</span> <span class="n">handle</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxObstacle</span><span class="o">&</span> <span class="n">obstacle</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>Typically <em>updateObstacle</em> is called right before the controllers' <em>move</em> calls.</p> +<p>Using obstacles for moving platforms is illustrated in SampleBridges, when PLATFORMS_AS_OBSTACLES is defined in SampleBridgesSettings.h.</p> +</div> +<div class="section" id="hit-callback"> +<h2>Hit Callback<a class="headerlink" href="#hit-callback" title="Permalink to this headline">¶</a></h2> +<p>The <em>PxUserControllerHitReport</em> object is used to retrieve some information about controller's evolution. In particular, it is called when a character hits a shape, another character, or a user-defined obstacle object.</p> +<p>When the character hits a shape, the <em>PxUserControllerHitReport::onShapeHit</em> callback is invoked - for both static and dynamic shapes. Various impact parameters are sent to the callback, and they can then be used to do various things like playing sounds, rendering trails, applying forces, and so on. The use of <em>PxUserControllerHitReport::onShapeHit</em> is illustrated in SampleBridges. Note that this callback will only be called in response to a character moving against a shape. It will <em>not</em> be called if a (dynamic) shape collides against an otherwise non-moving character. In other words, this will only be called during a <em>PxController::move</em> call.</p> +<p>When the character hits another character, i.e. another object controlled by a character controller, the <em>PxUserControllerHitReport::onControllerHit</em> callback is invoked. This happens when the player collides with an NPC, for example.</p> +<p>Finally, when the character hits a user-defined obstacle the <em>PxUserControllerHitReport::onObstacleHit</em> callback is invoked.</p> +</div> +<div class="section" id="behavior-callback"> +<h2>Behavior Callback<a class="headerlink" href="#behavior-callback" title="Permalink to this headline">¶</a></h2> +<p>The <em>PxControllerBehaviorCallback</em> object is used to customize the character's behavior after touching a <em>PxShape</em>, a <em>PxController</em>, or a <em>PxObstacle</em>. This is done using the following functions:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxControllerBehaviorFlags</span> <span class="n">PxControllerBehaviorCallback</span><span class="o">::</span><span class="n">getBehaviorFlags</span> + <span class="p">(</span><span class="k">const</span> <span class="n">PxShape</span><span class="o">&</span> <span class="n">shape</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxActor</span><span class="o">&</span> <span class="n">actor</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="n">PxControllerBehaviorFlags</span> <span class="n">PxControllerBehaviorCallback</span><span class="o">::</span><span class="n">getBehaviorFlags</span> + <span class="p">(</span><span class="k">const</span> <span class="n">PxController</span><span class="o">&</span> <span class="n">controller</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="n">PxControllerBehaviorFlags</span> <span class="n">PxControllerBehaviorCallback</span><span class="o">::</span><span class="n">getBehaviorFlags</span> + <span class="p">(</span><span class="k">const</span> <span class="n">PxObstacle</span><span class="o">&</span> <span class="n">obstacle</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>At the time of writing the following returned flags are supported:</p> +<p><em>PxControllerBehaviorFlag::eCCT_CAN_RIDE_ON_OBJECT</em> defines if the character can effectively travel with the object it is standing on. For example a character standing on a dynamic bridge should follow the motion of the PxShape it is standing on (e.g. in SampleBridges). But it should not be the case if the character stands on, say a PxShape bottle rolling on the ground (e.g. the snowballs in SampleNorthPole). Note that this flag only controls the horizontal displacement communicated from an object to the controller. The vertical motion is something slightly different, as many factors contribute to this displacement: the <em>step offset</em> used to automatically walk over small bumps, the vertical motion of underlying dynamic actors like e.g. the bridges in SampleBridges, which should probably always been taken into account, etc.</p> +<p><em>PxControllerBehaviorFlag::eCCT_SLIDE</em> defines if the character should slide or not when standing on the object. This can be used as an alternative to the previously discussed slope limit feature, to define non walk-able objects rather than non-walkable parts. It can also be used to make a capsule character fall off a platform's edge automatically, when the center of the capsule crosses the platform's edge.</p> +<p><em>PxControllerBehaviorFlag::eCCT_USER_DEFINED_RIDE</em> simply disables all built-in code related to controllers riding on objects. This can be useful to get the legacy behavior back, which can sometimes be necessary when porting to PhysX 3.x a piece of code built around the PhysX 2.x character controller. The flag simply skips the new codepath, and lets users deal with this particular problem in their own application, outside of the CCT library.</p> +<p>The behavior callback is demonstrated in SampleBridges.</p> +</div> +<div class="section" id="character-interactions-cct-vs-dynamic-actors"> +<h2>Character Interactions: CCT-vs-dynamic actors<a class="headerlink" href="#character-interactions-cct-vs-dynamic-actors" title="Permalink to this headline">¶</a></h2> +<p>It is tempting to let the physics engine push dynamic objects by applying forces at contact points. However it is often not a very convincing solution.</p> +<p>The bounding volumes around characters are artificial (boxes, capsules, etc) and invisible, so the forces computed by the physics engine between a bounding volume and its surrounding objects will not be realistic anyway. They will not properly model the interaction between an actual character and these objects. If the bounding volume is large compared to the visible character, maybe to make sure that its limbs never penetrate the static geometry around, the dynamic objects will start moving (pushed by a bounding volume) before the actual character touches them - making it look like the character is surrounded by some kind of force field.</p> +<p>Additionally, the pushing effect should not change when switching from a box controller to a capsule controller. It should ideally be independent from the bounding volume.</p> +<p>Pushing effects are usually dictated by gameplay, and sometimes require extra code like inverse kinematic solvers, which are outside of the scope of the CCT module. Even for simple use cases, it is for example difficult to push a dynamic box forward with a capsule controller: since the capsule never hits the box exactly in the middle, applied force tends to rotate the box - even if gameplay dictates that it should move in a straight line.</p> +<p>Thus, this is an area where the CCT module should best be coupled to specific game code, to implement a specific solution for a specific game. This coupling can be done in many different ways. For simple use cases it is enough to use the <em>PxUserControllerHitReport::onShapeHit</em> callback to apply artificial forces to surrounding dynamic objects. Such an approach is illustrated in SampleBridges.</p> +<p>Note that the character controller does use overlap queries to determine which shapes are nearby. Thus, SDK shapes that should interact with the characters (e.g. the objects that the character should push) must have the PxShapeFlag::eSCENE_QUERY_SHAPE flag set to true, otherwise the CCT will not detect them and characters will move right through these shapes.</p> +</div> +<div class="section" id="character-interactions-cct-vs-cct"> +<h2>Character Interactions: CCT-vs-CCT<a class="headerlink" href="#character-interactions-cct-vs-cct" title="Permalink to this headline">¶</a></h2> +<p>The interactions between CCTs (i.e. between two PxController objects) are limited, since in this case both objects are effectively kinematic objects. In other words their motion should be fully controlled by users, and neither the PhysX SDK nor the CCT module should be allowed to move them.</p> +<p>The <em>PxControllerFilterCallback</em> object is used to define basic interactions between characters. Its <em>PxControllerFilterCallback::filter</em> function can be used to determine if two PxController objects should collide at all with each other:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">PxControllerFilterCallback</span><span class="o">::</span><span class="n">filter</span><span class="p">(</span><span class="k">const</span> <span class="n">PxController</span><span class="o">&</span> <span class="n">a</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxController</span><span class="o">&</span> <span class="n">b</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>To make CCTs always collide-and-slide against each other, simply return true.</p> +<p>To make CCTs always move freely through each other, simply return false.</p> +<p>Otherwise, customized and maybe gameplay-driven filtering rules can be implemented in this callback. Sometimes the filtering changes at runtime, and two characters might be allowed to go through each other only for a limited amount of time. When that limited time expires, the characters may be left in an overlapping state until they separate and move again towards each other. To automatically separate overlapping characters, the following function can be used:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">computeInteractions</span><span class="p">(</span><span class="n">PxF32</span> <span class="n">elapsedTime</span><span class="p">,</span> + <span class="n">PxControllerFilterCallback</span><span class="o">*</span> <span class="n">cctFilterCb</span><span class="o">=</span><span class="nb">NULL</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>This function is an optional helper to properly resolve overlaps between characters. It should be called once per frame, before the <em>PxController::move</em> calls. The function will not move the characters directly, but it will compute overlap information for each character that will be used in the next <em>PxController::move</em> call.</p> +</div> +<div class="section" id="hidden-kinematic-actors"> +<h2>Hidden Kinematic Actors<a class="headerlink" href="#hidden-kinematic-actors" title="Permalink to this headline">¶</a></h2> +<p>The CCT library creates a kinematic actor under the hood, for each controlled character. When invoking the <em>PxController::move</em> function, the underlying hidden kinematic <em>PxActor</em> is also updated to reflect the CCT position in the physics scene.</p> +<p>Users should be aware of these hidden entities, since the total number of actors in the scene will be higher than the number they created themselves. Additionally they might get back these potentially confusing unknown actors from scene-level collision queries.</p> +<p>One possible strategy is to retrieve the controllers' kinematic actors using the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">PxController</span><span class="o">::</span><span class="n">getActor</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> +</pre></div> +</div> +<p>Then mark these actors with a special tag, using the <em>PxRigidDynamic::userData</em> field. That way the CCT actors can easily be identified (and possibly ignored) in collision queries or contact reports.</p> +</div> +<div class="section" id="time-stepping"> +<h2>Time Stepping<a class="headerlink" href="#time-stepping" title="Permalink to this headline">¶</a></h2> +<p>Actors used internally by the CCT library follow the same rules as any other PhysX objects. In particular, they are updated using fixed or variable timesteps. This can be troublesome because the PxController objects are otherwise often updated using variable time steps (typically using the elapsed time between two rendering frames).</p> +<p>Thus the PxController objects (using variable time steps) may not always be perfectly in sync with their kinematic actors (using fixed time steps). This phenomenon is shown in SampleBridges.</p> +</div> +<div class="section" id="invalidating-internal-geometry-caches"> +<h2>Invalidating Internal Geometry Caches<a class="headerlink" href="#invalidating-internal-geometry-caches" title="Permalink to this headline">¶</a></h2> +<p>The CCT library caches the geometry around each character, in order to speed up collision queries. The temporal bounding box for a character is an AABB around the character's motion (it contains the character's volume at both its start and end position). The cached volume of space is determined by the size of the character's temporal bounding box, multiplied by a constant factor. This constant factor is defined for each character by <em>PxControllerDesc::volumeGrowth</em>. Each time a character moves, its temporal bounding box is tested against the cached volume of space. If the motion is fully contained within that volume of space, the contents of the cache are reused instead of regenerated through PxScene-level queries.</p> +<img alt="../_images/cctCacheBounds.png" src="../_images/cctCacheBounds.png" /> +<p>In PhysX 3.3 and above, those caches should be automatically invalidated when a cached object gets updated or removed. However it is also possible to manually flush those caches using the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxController</span><span class="o">::</span><span class="n">invalidateCache</span><span class="p">();</span> +</pre></div> +</div> +<p>Prior to deciding if a character will travel with the motion of an object that is touching the character, a number of tests are automatically performed to decide if the cached touched object remains valid. These automatic validity tests mean that in the following cases it is not strictly necessary to invalidate the cache:</p> +<ul class="simple"> +<li>If the shapes actor is released</li> +<li>If the shape is released</li> +<li>If the shape is removed from an actor</li> +<li>If an actor is removed from scene or moved to another one</li> +<li>If the shapes scene query flag changed</li> +<li>If the filtering parameters of the shape or the scene have changed.</li> +</ul> +<p>If a cached touched object is no longer actually touching the character and it is desired that the character no longer travels with the motion of that cached object then it is necessary to invalidate the cache. This holds true if the pair have separated as a consequence of an updated global pose or modified geometry.</p> +</div> +<div class="section" id="runtime-tessellation"> +<h2>Runtime Tessellation<a class="headerlink" href="#runtime-tessellation" title="Permalink to this headline">¶</a></h2> +<p>The CCT library is quite robust, but sometimes suffers from FPU accuracy issues when a character collides against large triangles. This can lead to characters not smoothly sliding against those triangles, or even penetrating them. One way to effectively solve these problems is to tessellate the large triangles at runtime, replacing them on-the-fly with a collection of smaller triangles. The library supports a built-in tessellation feature, enabled with this function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxControllerManager</span><span class="o">::</span><span class="n">setTessellation</span><span class="p">(</span><span class="kt">bool</span> <span class="n">flag</span><span class="p">,</span> <span class="kt">float</span> <span class="n">maxEdgeLength</span><span class="p">);</span> +</pre></div> +</div> +<p>The first parameter enables or disables the feature. The second parameter defines the maximum allowed edge length for a triangle, before it gets tessellated. Obviously, a smaller edge length leads to more triangles being created at runtime, and the more triangles get generated, the slower it is to collide against them.</p> +<p>It is thus recommended to disable the feature at first, and only enable it if experiencing collision problems. When enabling the feature, it is recommended to use the largest possible <em>maxEdgeLength</em> that does fix encountered problems.</p> +<img alt="../_images/cctTessellation.png" src="../_images/cctTessellation.png" /> +<p>In the screenshot, the large magenta triangle on which the character is standing is replaced with the smaller green triangles by the tessellation module. The internal geometry cache is represented by the blue bounding box. Note that only the green triangles touching this volume of space are kept. Thus, the exact number of triangles produced by the tessellation code depends on both the <em>maxEdgeLength</em> parameter and the <em>PxControllerDesc::volumeGrowth</em> parameter.</p> +</div> +<div class="section" id="troubleshooting"> +<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2> +<p>This section introduces common solutions to common problems with the CCT library.</p> +<div class="section" id="character-goes-through-walls-in-rare-cases"> +<h3>Character goes through walls in rare cases<a class="headerlink" href="#character-goes-through-walls-in-rare-cases" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Try increasing <em>PxControllerDesc::contactOffset</em>.</li> +<li>Try enabling runtime tessellation with <em>PxControllerManager::setTessellation</em>. Start with a small <em>maxEdgeLength</em> first, to see if it solves the problem. Then increase that value as much as possible.</li> +<li>Try enabling overlap recovery module with <em>PxControllerManager::setOverlapRecoveryModule</em>.</li> +</ol> +</div> +<div class="section" id="tessellation-performance-issue"> +<h3>Tessellation performance issue<a class="headerlink" href="#tessellation-performance-issue" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Try fine-tuning the <em>maxEdgeLength</em> parameter. Use the largest possible value that still prevents tunneling issues.</li> +<li>Try reducing <em>PxControllerDesc::volumeGrowth</em>.</li> +</ol> +</div> +<div class="section" id="the-capsule-controller-manages-to-climb-over-obstacles-higher-than-the-step-offset-value"> +<h3>The capsule controller manages to climb over obstacles higher than the step offset value<a class="headerlink" href="#the-capsule-controller-manages-to-climb-over-obstacles-higher-than-the-step-offset-value" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Try using <em>PxCapsuleClimbingMode::eCONSTRAINED</em>.</li> +</ol> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Character Controllers</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#kinematic-character-controller">Kinematic Character Controller</a></li> +<li><a class="reference internal" href="#creating-a-character-controller">Creating a character controller</a></li> +<li><a class="reference internal" href="#overlap-recovery-module">Overlap Recovery Module</a></li> +<li><a class="reference internal" href="#character-volume">Character Volume</a></li> +<li><a class="reference internal" href="#volume-update">Volume Update</a></li> +<li><a class="reference internal" href="#moving-a-character-controller">Moving a Character Controller</a></li> +<li><a class="reference internal" href="#graphics-update">Graphics Update</a></li> +<li><a class="reference internal" href="#auto-stepping">Auto Stepping</a></li> +<li><a class="reference internal" href="#climbing-mode">Climbing Mode</a></li> +<li><a class="reference internal" href="#up-vector">Up Vector</a></li> +<li><a class="reference internal" href="#walkable-parts-invisible-walls">Walkable Parts & Invisible Walls</a></li> +<li><a class="reference internal" href="#obstacle-objects">Obstacle Objects</a></li> +<li><a class="reference internal" href="#hit-callback">Hit Callback</a></li> +<li><a class="reference internal" href="#behavior-callback">Behavior Callback</a></li> +<li><a class="reference internal" href="#character-interactions-cct-vs-dynamic-actors">Character Interactions: CCT-vs-dynamic actors</a></li> +<li><a class="reference internal" href="#character-interactions-cct-vs-cct">Character Interactions: CCT-vs-CCT</a></li> +<li><a class="reference internal" href="#hidden-kinematic-actors">Hidden Kinematic Actors</a></li> +<li><a class="reference internal" href="#time-stepping">Time Stepping</a></li> +<li><a class="reference internal" href="#invalidating-internal-geometry-caches">Invalidating Internal Geometry Caches</a></li> +<li><a class="reference internal" href="#runtime-tessellation">Runtime Tessellation</a></li> +<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul> +<li><a class="reference internal" href="#character-goes-through-walls-in-rare-cases">Character goes through walls in rare cases</a></li> +<li><a class="reference internal" href="#tessellation-performance-issue">Tessellation performance issue</a></li> +<li><a class="reference internal" href="#the-capsule-controller-manages-to-climb-over-obstacles-higher-than-the-step-offset-value">The capsule controller manages to climb over obstacles higher than the step offset value</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Vehicles.html" + title="previous chapter">Vehicles</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Particles.html" + title="next chapter">Particles (deprecated)</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" /> + <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="Particles.html" title="Particles (deprecated)" + >next</a></li> + <li class="right" > + <a href="Vehicles.html" title="Vehicles" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Cloth.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Cloth.html new file mode 100644 index 00000000..23d24214 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Cloth.html @@ -0,0 +1,551 @@ +<!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>Cloth — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Debug Visualization" href="DebugVisualization.html" /> + <link rel="prev" title="Particles (deprecated)" href="Particles.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="DebugVisualization.html" title="Debug Visualization" + accesskey="N">next</a></li> + <li class="right" > + <a href="Particles.html" title="Particles (deprecated)" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="cloth"> +<span id="id1"></span><h1>Cloth<a class="headerlink" href="#cloth" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>Realistic movement of character clothing greatly improves the player experience. The PhysX 3 cloth feature is a complete and high-performance solution to simulate character clothing. It provides local space simulation for high accuracy and stability, new techniques to reduce stretching, collision against a variety of shapes, as well as particle self-collision and inter-collision to avoid the cloth penetrating itself or other cloth instances. The simulation can be offloaded to CUDA capable GPUs for better performance or to run assets at higher resolutions than the CPU is able to handle.</p> +<p>PhysX 3 cloth is a rewrite of the PhysX 2 deformables, tailored towards simulating character cloth. Softbodies, tearing, and two-way interaction have been removed, while behavior and performance for cloth simulation have been improved.</p> +</div> +<div class="section" id="simulation-algorithm"> +<h2>Simulation Algorithm<a class="headerlink" href="#simulation-algorithm" title="Permalink to this headline">¶</a></h2> +<p>For one PhysX simulation frame, the cloth solver runs for multiple iterations. The number of iterations is determined by the solver frequency parameter and the simulation frame time. Each iteration integrates particle positions, solves constraints, and performs character and self-collision. Cloth inter-collision is performed once per-frame after all cloth instances in the scene have been stepped forward. Local frame, motion constraints and collision shapes are interpolated per iteration from the per-frame values specified by the user.</p> +<div class="section" id="solver-frequency"> +<h3>Solver Frequency<a class="headerlink" href="#solver-frequency" title="Permalink to this headline">¶</a></h3> +<p>The size of the iteration time step is inversely proportional to the number of solver iterations:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setSolverFrequency</span><span class="p">(</span><span class="mf">240.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>The solver frequency is specified as iterations per second. A solver frequency value of 240 corresponds to 4 iterations per frame at 60 frames per second. In general, simulation will become more accurate if higher solver frequency value is used. However, simulation time grows roughly linearly with solver frequency. Typically this value is between 120 and 300.</p> +<p>The number of iterations for each frame is derived using the simulation frequency and the simulation time-step. PhysX tries to handle variable time-steps carefully, by taking variations of the time-step into account during position integration and when applying damping parameters like constraint stiffness. While this reduces the possible jittering artifacts due to varying time step sizes, use of variable time step size is generally not recommended.</p> +</div> +<div class="section" id="particle-integration"> +<h3>Particle Integration<a class="headerlink" href="#particle-integration" title="Permalink to this headline">¶</a></h3> +<p>The first step in a cloth iteration predicts the new particle position based on its current position, velocity and external acceleration. While a particle state consists of the current position and the position before the last iteration, the particle velocity in local space can be computed by dividing the position delta by the delta time of the previous iteration.</p> +</div> +<div class="section" id="local-space-simulation-and-inertia-scale"> +<h3>Local Space Simulation and Inertia Scale<a class="headerlink" href="#local-space-simulation-and-inertia-scale" title="Permalink to this headline">¶</a></h3> +<p>Each PxCloth actor has a transformation that transforms particles from its local space to world space positions. For example:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setGlobalPose</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.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> +</pre></div> +</div> +<p>will change the cloth's world space position to (1,0,0). Now compare that to this function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setTargetPose</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.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> +</pre></div> +</div> +<p>, which also changes the cloth's position to the same place. So what's different?</p> +<p><em>PxCloth::setGlobalPose()</em> only moves the cloth, but <em>PxCloth::setTargetPose()</em> also generates acceleration (inertia) due to the position change. +The amount by which the local frame acceleration affects the cloth particles can be controlled using an inertia scale, for example to impart half the local frame acceleration to the particles use:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setInertiaScale</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">);</span> +</pre></div> +</div> +<p>Scaling inertia effects individually per translation and rotation axis is also possible through the family of PxCloth::set*InertiaScale() methods. +Limiting the amount that local frame accelerations affect particles can be especially useful for fast moving characters.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Using setGlobalPose() is equivalent to using setTargetPos() when inertia scale is 0. In this case, the cloth does not receive any acceleration due to frame changes.</p> +</div> +</div> +<div class="section" id="constraints"> +<h3>Constraints<a class="headerlink" href="#constraints" title="Permalink to this headline">¶</a></h3> +<p>After the particle positions have been integrated, a set of different constraints are solved to simulate stretch, shear and bending forces, as well as to confine the particle movement within a certain region.</p> +</div> +<div class="section" id="distance-constraints"> +<h3>Distance Constraints<a class="headerlink" href="#distance-constraints" title="Permalink to this headline">¶</a></h3> +<div class="figure align-center"> +<img alt="../_images/ClothStretchConstraint.png" src="../_images/ClothStretchConstraint.png" /> +<p class="caption">Figure 1. Typical configuration for vertical (left), and horizontal (right) stretching constraints</p> +</div> +<div class="figure align-center"> +<img alt="../_images/ClothShearingConstraint.png" src="../_images/ClothShearingConstraint.png" /> +<p class="caption">Figure 2. Typical configuration for shearing distance constraints</p> +</div> +<div class="figure align-center"> +<img alt="../_images/ClothBendingConstraint.png" src="../_images/ClothBendingConstraint.png" /> +<p class="caption">Figure 3. Typical configuration for vertical (left), and horizontal (right) bending constraints, note bending constraints typically span more than one edge in the mesh</p> +</div> +<p>One of the most important roles for the cloth solver is to maintain distance between particles so that the cloth does not stretch. This is achieved by applying distance constraints between pairs of particles. The way particles are connected affects how the cloth stretches, compresses, shears, rotates, and bends. PhysX classifies distance constraints into 4 types (see <em>PxClothFabricPhaseType</em>), each of which can be configured with different stiffness parameters.</p> +<p>Below is an example of stiffness settings for each constraint type:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setStretchConfig</span><span class="p">(</span><span class="n">PxClothFabricPhaseType</span><span class="o">::</span><span class="n">eVERTICAL</span><span class="p">,</span> <span class="n">PxClothStretchConfig</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">));</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setStretchConfig</span><span class="p">(</span><span class="n">PxClothFabricPhaseType</span><span class="o">::</span><span class="n">eHORIZONTAL</span><span class="p">,</span> <span class="n">PxClothStretchConfig</span><span class="p">(</span><span class="mf">0.9f</span><span class="p">));</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setStretchConfig</span><span class="p">(</span><span class="n">PxClothFabricPhaseType</span><span class="o">::</span><span class="n">eSHEARING</span><span class="p">,</span> <span class="n">PxClothStretchConfig</span><span class="p">(</span><span class="mf">0.75f</span><span class="p">));</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setStretchConfig</span><span class="p">(</span><span class="n">PxClothFabricPhaseType</span><span class="o">::</span><span class="n">eBENDING</span><span class="p">,</span> <span class="n">PxClothStretchConfig</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">));</span> +</pre></div> +</div> +<p>Sometimes it is desirable that distance constraints are not enforced rigorously. The stiffness parameter allows only correcting a portion of the edge length residual per iteration, for example to reduce the strength of bending constraints. A separate, lower stiffness can be used for edges that are only moderately stretched or compressed. For example, a dress can be made to stretch when the character is taking large steps, but still behave correctly during pirouettes.</p> +<p>The following code sets up the vertical constraints such that when edges are compressed more than 60% or stretched more than 120%, a stiffness of 0.8 will be used. Otherwise a stiffness of 0.4 = 0.8 * 0.5 will be used:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxClothStretchConfig</span> <span class="n">stretchConfig</span><span class="p">;</span> +<span class="n">stretchConfig</span><span class="p">.</span><span class="n">stiffness</span> <span class="o">=</span> <span class="mf">0.8f</span><span class="p">;</span> +<span class="n">stretchConfig</span><span class="p">.</span><span class="n">stiffnessMultiplier</span> <span class="o">=</span> <span class="mf">0.5f</span><span class="p">;</span> +<span class="n">stretchConfig</span><span class="p">.</span><span class="n">compressionLimit</span> <span class="o">=</span> <span class="mf">0.6f</span><span class="p">;</span> +<span class="n">stretchConfig</span><span class="p">.</span><span class="n">stretchLimit</span> <span class="o">=</span> <span class="mf">1.2f</span><span class="p">;</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setStretchConfig</span><span class="p">(</span><span class="n">PxClothFabricPhaseType</span><span class="o">::</span><span class="n">eVERTICAL</span><span class="p">,</span> <span class="n">stretchConfig</span><span class="p">);</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Stretch settings for horizontal and vertical directions are specified separately. This can be used to handle stretching along the gravity (vertical) direction differently.</p> +</div> +</div> +<div class="section" id="tether-constraints"> +<h3>Tether Constraints<a class="headerlink" href="#tether-constraints" title="Permalink to this headline">¶</a></h3> +<div class="figure align-center"> +<img alt="../_images/ClothTetherConstraint.png" src="../_images/ClothTetherConstraint.png" /> +<p class="caption">Figure 4. Example tether constraint configuration</p> +</div> +<p>The distance constraints are solved only once per iteration without converging completely. The most visible artifact of this approximation is that the cloth becomes stretchy. Increasing solver frequency reduces the stretching, but results in increased simulation time.</p> +<p>PhysX 3.3 introduces tether constraints as a solution to avoid stretchiness under gravity or fast motion. Tether constraints prevent stretching by limiting the distance a particle can move away from their anchor particles. This constraint adds very small amount of computation to the solver, so it is more effective than increasing the number of iterations.</p> +<p>The tether constraints are automatically generated by the cooker when some <em>PxClothMeshDesc::invMasses</em> values are set to zero, telling the cooker that the corresponding particles are non-simulated anchor particles whose positions are provided solely from users. Changing inverse masses after the fabric has been created does not affect which anchor particles are used for the tether constraints.</p> +</div> +<div class="section" id="motion-constraints"> +<h3>Motion Constraints<a class="headerlink" href="#motion-constraints" title="Permalink to this headline">¶</a></h3> +<div class="figure align-center"> +<img alt="../_images/ClothMotionConstraint.png" src="../_images/ClothMotionConstraint.png" /> +<p class="caption">Figure 5. Example motion constraint</p> +</div> +<p>One can fully constrain a point to user specified position with zero inverse mass. However, it is sometimes desirable to confine a point within small region around the animated (user specified) position. This allows small details to be generated by simulation, while suppressing any excessive deviation from the desired position.</p> +<p><em>Motion constraints</em> lock the movement of each particle inside a sphere. For example, an animation system can sketch the overall movement of a cloth while the fine scale details are handled by the cloth simulation.</p> +<p><em>PxClothParticleMotionConstraint</em> structure holds the position and radius of the sphere for each particle, and motion constraints can be specified as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxClothParticleMotionConstraints</span> <span class="n">motionConstraints</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> + <span class="n">PxClothParticleMotionConstraints</span><span class="p">(</span><span class="n">PxVec3</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">0.0f</span><span class="p">),</span> + <span class="n">PxClothParticleMotionConstraints</span><span class="p">(</span><span class="n">PxVec3</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="mf">0.0f</span><span class="p">),</span> <span class="mf">1.0f</span><span class="p">),</span> + <span class="n">PxClothParticleMotionConstraints</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.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">PxClothParticleMotionConstraints</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">),</span> <span class="n">FLT_MAX</span><span class="p">)</span> +<span class="p">};</span> + +<span class="n">cloth</span><span class="p">.</span><span class="n">setMotionConstraints</span><span class="p">(</span><span class="n">motionConstraints</span><span class="p">);</span> +</pre></div> +</div> +<p>If the sphere radius becomes zero or negative, the corresponding particle is locked at the sphere center and the inverse particle mass is set to zero for the next iteration. In the above example, the first particle will fully lock to the constraint position, while the second and third particle will remain within the sphere radius. The last particle will not be constrained.</p> +<p>The motion constraint sphere radius can be globally scaled and biased, for example to transition between simulated and animated states. See <em>PxClothMotionConstraintConfig</em> for details.</p> +</div> +<div class="section" id="separation-constraints"> +<h3>Separation Constraints<a class="headerlink" href="#separation-constraints" title="Permalink to this headline">¶</a></h3> +<div class="figure align-center"> +<img alt="../_images/ClothSeparationConstraint.png" src="../_images/ClothSeparationConstraint.png" /> +<p class="caption">Figure 6. Example separation constraint</p> +</div> +<p>Separation constraints work exactly the opposite way to the motion constraints, forcing a particle to stay outside of a sphere. When particle movement is moderately constrained by motion constraints (e.g. sleeves around an arm), separation constraints can be used to represent the character's collision shape more accurately than using capsules alone. For example, separation constraints can be placed slightly inside the character by setting the radius to be the distance from the sphere center to the surface of the character.</p> +<p>See <em>PxClothParticleSeperationConstraint</em> and <em>PxCloth::setSeparationConstraints()</em>.</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>Each cloth object supports collision with spheres, capsules, planes, convexes (groups of planes) and triangles. By default these shapes are all treated separately from the main PhysX rigid body scene, however collision against other PxScene actors can be enabled using the PxClothFlag::eSCENE_COLLISION flag.</p> +<p>Collision shapes are specified in local coordinates for the next frame before simulating the scene. An independent and complete collision stage is performed as part of each solver iteration, using shape positions interpolated from the values at the beginning and the end of the frame. Sphere and capsule collision supports continuous collision detection and use an acceleration structure to cull far-away particles early in the collision pipeline. Spheres and capsules are therefore the preferred choice to model the character shape, and convexes and triangles should only be used sparingly.</p> +<p>Spheres are defined as center and radius. Note that the radius is specifically allowed to change from frame to frame. The total number of spheres is limited to 32 per cloth.</p> +<p>Capsules are defined by a pair of indices into the spheres array and each sphere may have a different radius thus forming a tapered capsule. Spheres can be shared between multiple capsules, which can be useful for modeling characters (upper and lower leg made up from capsules can share the sphere at the knee). Sharing of spheres also makes the simulation more efficient and robust, so is highly encouraged.</p> +<div class="figure align-center"> +<img alt="../_images/ClothCapsuleShape.png" src="../_images/ClothCapsuleShape.png" /> +<p class="caption">Figure 7. A tapered capsule collision shape formed by two connected spheres</p> +</div> +<div class="figure align-center"> +<img alt="../_images/ClothLegShape.png" src="../_images/ClothLegShape.png" /> +<p class="caption">Figure 8. A leg shape formed by using two tapered capsules, each sharing a sphere at the middle</p> +</div> +<p>Planes are defined by their normal and distance to origin. They will not be considered for collision unless they are referenced by a convex shape. Convexes reference planes using a mask, where each bit corresponds to an entry in the array of planes. There is a limit of 32 planes per cloth.</p> +<p>Triangle colliders are defined as vertex triplets in counter-clockwise winding order. The triangles should form a closed patch near the cloth for consistent collision handling (each particle collides against its closest triangle expanded to an infinite plane).</p> +<p>The order of planes and triangles should remain unchanged (apart from removing them through the <em>PxCloth::removeCollisionPlane/Triangle()</em> method) as their positions are interpolated between simulation frames.</p> +</div> +<div class="section" id="continuous-collision-detection"> +<h3>Continuous Collision Detection<a class="headerlink" href="#continuous-collision-detection" title="Permalink to this headline">¶</a></h3> +<p>Besides discrete collision which resolves particles inside shapes at the end of each iteration, continuous collision detection is supported and can be enabled by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Enable continuous collision detection</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setClothFlag</span><span class="p">(</span><span class="n">PxClothFlag</span><span class="o">::</span><span class="n">eSWEPT_CONTACT</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Continuous collision is around 2x more computationally expensive than discrete collision, but it is necessary to detect collision between fast moving objects. Continuous collision analyzes the trajectory of particles and capsules to determine when a contact occurs. After the first time of contact, the particle is moved with the shape until the end of the iteration.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The SIMD collision path handles sets of 4 particles in parallel. It is therefore advantageous to spatially group cloth particles so that they are likely to collide with the same set of shapes.</p> +</div> +</div> +<div class="section" id="virtual-particle-collision"> +<h3>Virtual Particle Collision<a class="headerlink" href="#virtual-particle-collision" title="Permalink to this headline">¶</a></h3> +<p>Virtual particles provide a way of improving cloth collision without increasing the cloth resolution. They are called 'virtual' particles because they only exist during the collision processing stage and do not have their position, velocity or mass explicitly stored like regular particles, they can be thought of as providing additional samples on the collision surface.</p> +<p>During collision processing each virtual particle is created from three normal particles using barycentric interpolation. It is then tested for discrete collision like a regular particle and the collision impulse is redistributed back to the original particles using reverse interpolation.</p> +<p>Section <a class="reference internal" href="#vpsnippet"><em>Adding Virtual Particles</em></a> explains the necessary steps to use this feature.</p> +</div> +<div class="section" id="friction-and-mass-scaling"> +<h3>Friction and Mass Scaling<a class="headerlink" href="#friction-and-mass-scaling" title="Permalink to this headline">¶</a></h3> +<p>Coulomb friction can be enabled and will be applied for particle and virtual particle collisions by setting a friction coefficient between 0 and 1:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setFrictionCoefficient</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">);</span> +</pre></div> +</div> +<p>Additionally, there is an option to artificially increase the mass of colliding particles, this temporary increase in mass can help reduce stretching along edges that are being tightly pulled over a collision shape. The effect is determined by the relative normal velocity of the particle and collision shape and a user defined coefficient. A value of 20 is reasonable starting point but users are encouraged to experiment with this value:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setCollisionMassScale</span><span class="p">(</span><span class="mf">20.0f</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="self-collision-of-a-single-cloth-actor"> +<h3>Self-Collision of a Single Cloth Actor<a class="headerlink" href="#self-collision-of-a-single-cloth-actor" title="Permalink to this headline">¶</a></h3> +<p>The particles of a cloth actor can collide among themselves. +To enable this self-collision behavior, one should set both self-collision distance and self-collision stiffness to non-zero values:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setSelfCollisionDistance</span><span class="p">(</span><span class="mf">0.1f</span><span class="p">);</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setSelfCollisionStiffness</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>Self-collision distance defines the diameter of a sphere around each particle, and the solver ensures that these spheres do not overlap during simulations. +Self-collision stiffness defines how strong the separating impulse should be.</p> +<p>Self-collision distance should be smaller than the smallest distance between two particles in the rest configuration. If the distance is larger, self-collision may violate some distance constraints and result in jittering.</p> +<p>When such a configuration cannot be avoided (e.g. due to irregular input meshes, etc.), one can assign additional rest positions:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setRestPositions</span><span class="p">(</span><span class="n">restPositions</span><span class="p">);</span> +</pre></div> +</div> +<p>Collision between two particles is ignored if their rest-positions are closer than the the collision distance. However, a large collision distance and use of rest positions will significantly degrade performance of self-collision, so should be used sparingly.</p> +<p>Self-collision performance for high-resolution cloth instances can be improved by limiting self-collision to a subset of all particles (see <em>PxCloth::setSelfCollisionIndices()</em>).</p> +</div> +<div class="section" id="inter-collision-between-multiple-cloth-actors"> +<h3>Inter-Collision between Multiple Cloth Actors<a class="headerlink" href="#inter-collision-between-multiple-cloth-actors" title="Permalink to this headline">¶</a></h3> +<p>Different cloth actors can be made to interact with each other when inter-collision is enabled. The parameters for inter-collision are set for all cloth instances of a scene:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="p">.</span><span class="n">setInterCollisionDistance</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">);</span> +<span class="n">scene</span><span class="p">.</span><span class="n">setInterCollisionStiffness</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>The definition of distance and stiffness values are the same as self-collision. Cloth instances that specify a particle subset for self-collision use the same subset for inter-collision.</p> +</div> +</div> +<div class="section" id="best-practices-troubleshooting"> +<h2>Best Practices / Troubleshooting<a class="headerlink" href="#best-practices-troubleshooting" title="Permalink to this headline">¶</a></h2> +<div class="section" id="performance-tips"> +<h3>Performance Tips<a class="headerlink" href="#performance-tips" title="Permalink to this headline">¶</a></h3> +<p>The runtime of the cloth simulation scales approximately linearly with the number of cloth particles and the solver frequency: Simulating a higher resolution mesh with more particles and increasing stretch stiffness and collision handling fidelity with higher solver frequencies increase the time it takes to simulate one frame. Additionally, there is a performance drop somewhere below 3000 particles for the GPU solver as explained in the next section. As a rough guideline, a dozen cloth instances with 2000 particles each and a solver frequency of 300Hz can be simulated in real-time as part of a game.</p> +<p>Convex collision and triangle collision do not use any mid phase acceleration structure, and are therefore slower than sphere and capsule collision.</p> +<p>Self-collision and inter-collision can take a significant amount of the overall simulation time. Consider keeping the collision distance small and using self-collision indices to reduce the number of particles that collide with each other.</p> +</div> +<div class="section" id="using-gpu-cloth"> +<h3>Using GPU Cloth<a class="headerlink" href="#using-gpu-cloth" title="Permalink to this headline">¶</a></h3> +<p>Cloth can be simulated on a CUDA or DirectCompute enabled GPU, by setting one of the corresponding flags:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">setClothFlag</span><span class="p">(</span><span class="n">PxClothFlag</span><span class="o">::</span><span class="n">eCUDA</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">setClothFlag</span><span class="p">(</span><span class="n">PxClothFlag</span><span class="o">::</span><span class="n">eDIRECT_COMPUTE</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>The entire cloth solver pipeline is run on the GPU, with the exception of inter-collision. When no supported GPU is available PhysX will issue a warning, and subsequent simulations will be run on CPU.</p> +<p>When the cloth is simulated using CUDA, the GPU simulation results can interop with the graphics API by requesting CUDA device pointers to the particle data:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">lockParticleData</span><span class="p">(</span><span class="n">PxDataAccessFlag</span><span class="o">::</span><span class="n">eDEVICE</span><span class="p">);</span> +</pre></div> +</div> +<p>To take full advantage of the GPU hardware there should be at least as many cloth instances as streaming multiprocessors (SMs). This means it is generally better to simulate clothing as multiple instances (e.g. shirts and skirt) rather than grouped into one instance.</p> +<p>GPU PhysX performance is better when the particle data of a cloth can fit in shared memory. The number of particles that fit into shared memory depends on the number of collision shapes, whether continuous collision or self-collisions are enabled, and also on the GPU version. For GPUs supporting SM 2.0 and above, about 2500-2900 particles fit into shared memory. If particles don't fit into shared memory the cloth solver will automatically stream particles through global memory, which incurs some performance cost.</p> +<p>Furthermore, the limited size of shared memory requires the number of collision triangles to be clamped to 500 when GPU simulation is enabled.</p> +</div> +<div class="section" id="fast-moving-characters"> +<h3>Fast-Moving Characters<a class="headerlink" href="#fast-moving-characters" title="Permalink to this headline">¶</a></h3> +<p>Consistent collision handling for fast-moving characters can be difficult. Fast translations and rotations are best handled by tying the cloth local simulation frame to the character transformation. The inertia effects of the local frame transformations can be fine-tuned using the inertia scale settings.</p> +<p>If the cloth tunnels collision shapes during fast character animations, try increasing the solver frequency or enabling swept contacts (see <em>PxClothFlag::eSWEPT_CONTACT</em>).</p> +</div> +<div class="section" id="avoiding-stretching"> +<h3>Avoiding Stretching<a class="headerlink" href="#avoiding-stretching" title="Permalink to this headline">¶</a></h3> +<p>Due to the iterative nature of the distance constraint solver, high resolution cloth can stretch undesirably under strong gravity even if the stretch stiffness is set to one. Increasing the solver frequency mitigates the stretching, but tether constraints are usually better suited to eliminate stretching efficiently.</p> +</div> +<div class="section" id="avoiding-jitter"> +<h3>Avoiding Jitter<a class="headerlink" href="#avoiding-jitter" title="Permalink to this headline">¶</a></h3> +<p>Under certain configurations, different constraint types can violate each other and over-constrain the particle positions. For example, a motion constraint can move the particle further from the anchor particle than the tether constraint permits, or particles can get pinched between two overlapping collision shapes. Over-constraining particle positions can result in jitter and should be avoided. In some situations jitter can be avoided by increasing the solver frequency or by reducing the corresponding constraint stiffness.</p> +</div> +<div class="section" id="pvd-support"> +<h3>PVD Support<a class="headerlink" href="#pvd-support" title="Permalink to this headline">¶</a></h3> +<p>Cloth particle positions, distance constraints, and collision shapes are rendered as points, lines, and wireframes respectively in PVD. The SDK does not have access to the mesh used to create the fabric, and this mesh can't be displayed in PVD either. However, you can display individual sets of distance constraints instead of all at once: set <em>Cloth Phase Mode</em> to <em>Single Phase</em> in the <em>Preferences</em> dialog and use the <em>Cloth Phase</em> slider to pick the phase to display. The <em>Particle Scale</em> slider in the same dialog affects the rendering size of ordinary and virtual cloth particles as well. All properties of a selected cloth object can be viewed in the <em>Inspector</em> panel of PVD.</p> +</div> +</div> +<div class="section" id="snippet-discussion"> +<h2>Snippet Discussion<a class="headerlink" href="#snippet-discussion" title="Permalink to this headline">¶</a></h2> +<p>The following paragraph describes code of the cloth snippet provided with the PhysX SDK.</p> +<p>The cloth constraint connectivity and rest values are stored in a fabric instance (<em>PxClothFabric</em>), separate from the cloth actor (<em>PxCloth</em>). The separation of the constraints from particles allows the same fabric data to be reused for multiple cloth instances, reducing cooking time and storage requirements. <em>PxClothFabricCreate</em>, in the extensions library, creates a fabric from a triangle or quad mesh (see <em>PxClothMeshDesc</em>). The cloth actor itself is created through the physics instance (<em>PxPhysics</em>) and needs to be added to a scene (<em>PxScene</em>) in order to be simulated. Once the cloth actor is created, users can assign simulation settings such as collision data, constraint stiffness, solver frequency and self-collision. The <em>createCloth</em> function in the cloth snippet performs these steps.</p> +<p>The <em>stepPhysics</em> function advances the simulation by one frame. It first updates the cloth local frame, which rotates around the y-axis. The collision shapes are not moving in scene coordinates, but their positions are specified in cloth local coordinates, and therefore need to be updated every frame. The following sections detail some of the available parameters and show how to configure them.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The cloth module has to be registered with <em>PxRegisterCloth</em> on platforms with static linking (non windows) before creating cloth objects. <em>PxCreatePhysics</em> registers all modules by default as opposed to <em>PxCreateBasePhysics</em>.</p> +</div> +<div class="section" id="filling-in-pxclothmeshdesc"> +<h3>Filling in PxClothMeshDesc<a class="headerlink" href="#filling-in-pxclothmeshdesc" title="Permalink to this headline">¶</a></h3> +<p>The first task to create a cloth is to fill in the <em>PxClothMeshDesc</em> structure. The snippet programmatically creates a regular grid of cloth particles connected by a quad mesh. Below is a simpler example on how to create a cloth from a simple mesh consisting of a single quad.</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxClothParticle</span> <span class="n">vertices</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> + <span class="n">PxClothParticle</span><span class="p">(</span><span class="n">PxVec3</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">0.0f</span><span class="p">),</span> + <span class="n">PxClothParticle</span><span class="p">(</span><span class="n">PxVec3</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="mf">0.0f</span><span class="p">),</span> <span class="mf">1.0f</span><span class="p">),</span> + <span class="n">PxClothParticle</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.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">PxClothParticle</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">,</span> <span class="mf">1.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">PxU32</span> <span class="n">primitives</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span> <span class="p">};</span> + +<span class="n">PxClothMeshDesc</span> <span class="n">meshDesc</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">vertices</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="mi">4</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">PxClothParticle</span><span class="p">);</span> + +<span class="n">meshDesc</span><span class="p">.</span><span class="n">invMasses</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="o">&</span><span class="n">vertices</span><span class="o">-></span><span class="n">invWeight</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">invMasses</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">invMasses</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">PxClothParticle</span><span class="p">);</span> + +<span class="n">meshDesc</span><span class="p">.</span><span class="n">quads</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">primitives</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">quads</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">quads</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">PxU32</span><span class="p">)</span> <span class="o">*</span> <span class="mi">4</span><span class="p">;</span> +</pre></div> +</div> +<p>Each particle is defined by its position in local coordinates and its inverse mass. Setting the inverse mass to zero indicates that the particle is not simulated. Instead, the particle is fixed in local space or kinematically constrained to user specified positions. The inverse mass of simulated particles can normally be set to any fixed positive value.</p> +<p>The <em>PxClothMeshDesc</em> structure allows positions and inverse masses stored in separate arrays or interleaved like in the code above. The mesh can consist of quads or triangles, or both. The cooker prefers quad meshes over triangle meshes when creating constraints and classifying constraint types. The extensions library therefore provides the <em>PxClothMeshQuadifier</em> helper class to extract quads from a triangle mesh.</p> +</div> +<div class="section" id="creating-fabric"> +<h3>Creating Fabric<a class="headerlink" href="#creating-fabric" title="Permalink to this headline">¶</a></h3> +<p>Given the mesh descriptor, a call to <em>PxClothFabricCreate</em> in the extensions library wraps the generation of constraints and the creation of the <em>PxClothFabric</em> structure:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxClothFabric</span><span class="o">*</span> <span class="n">fabric</span> <span class="o">=</span> <span class="n">PxClothFabricCreate</span><span class="p">(</span><span class="n">physics</span><span class="p">,</span> <span class="n">meshDesc</span><span class="p">,</span> <span class="n">PxVec3</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span> +</pre></div> +</div> +<p>The third parameter indicates the direction of gravity, which is used as a hint to determine the direction of 'horizontal' or 'vertical' constraints.</p> +<p>The <em>PxClothFabric</em> class describes internal solver data for a cloth. For example, distance constraints consisting of two particle indices and a rest-length are created by the cooker and stored in the fabric data. Multiple cloth instances of the same mesh can share a single fabric instance.</p> +</div> +<div class="section" id="creating-cloth"> +<h3>Creating Cloth<a class="headerlink" href="#creating-cloth" title="Permalink to this headline">¶</a></h3> +<p>A <em>PxCloth</em> object is created using a fabric instance and the initial particle configuration. Like all actors, the cloth instance is simulated as part of a scene:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxTransform</span> <span class="n">pose</span> <span class="o">=</span> <span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">);</span> +<span class="n">PxCloth</span><span class="o">*</span> <span class="n">cloth</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createCloth</span><span class="p">(</span><span class="n">pose</span><span class="p">,</span> <span class="n">fabric</span><span class="p">,</span> <span class="n">vertices</span><span class="p">,</span> <span class="n">PxClothFlags</span><span class="p">());</span> +<span class="n">scene</span><span class="p">.</span><span class="n">addActor</span><span class="p">(</span><span class="n">cloth</span><span class="p">);</span> +</pre></div> +</div> +<p>The first parameter specifies the initial pose. The second input is the fabric instance created by the cooker. The third input provides initial particle positions and inverse masses. Typically this array is the same as the one referenced by the mesh descriptor used to create the fabric. Note that the rest configuration (such as the rest-length for a distance constraint) is computed from PxClothMeshDesc, so the initial particle positions do not affect rest configuration. The last parameter is a set of flags that allow GPU simulation and continuous collision detection to be enabled. The default is to turn off both options.</p> +</div> +<div class="section" id="specifying-collision-shapes"> +<h3>Specifying Collision Shapes<a class="headerlink" href="#specifying-collision-shapes" title="Permalink to this headline">¶</a></h3> +<p>The following code illustrates how to add two spheres of different radius and create a tapered capsule between them:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Two spheres located on the x-axis</span> +<span class="n">PxClothCollisionSphere</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">PxClothCollisionSphere</span><span class="p">(</span> <span class="n">PxVec3</span><span class="p">(</span><span class="o">-</span><span class="mf">1.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">0.5f</span> <span class="p">),</span> + <span class="n">PxClothCollisionSphere</span><span class="p">(</span> <span class="n">PxVec3</span><span class="p">(</span> <span class="mf">1.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">0.25f</span> <span class="p">)</span> +<span class="p">};</span> + +<span class="n">cloth</span><span class="p">.</span><span class="n">setCollisionSpheres</span><span class="p">(</span><span class="n">spheres</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">addCollisionCapsule</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span> +</pre></div> +</div> +<p>Planes can be added through <em>PxCloth::addCollisionPlane()</em> method but will not be considered for collision unless they are referenced by a convex shape. For example, the following code shows how to setup a typical upward facing ground plane through the origin:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">cloth</span><span class="p">.</span><span class="n">addCollisionPlane</span><span class="p">(</span><span class="n">PxClothCollisionPlane</span><span class="p">(</span><span class="n">PxVec3</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="mf">0.0f</span><span class="p">),</span> <span class="mf">0.0f</span><span class="p">));</span> +<span class="n">cloth</span><span class="p">.</span><span class="n">addCollisionConvex</span><span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">);</span> <span class="c1">// Convex references the first plane</span> +</pre></div> +</div> +<p>Planes may be efficiently updated after construction using the <em>PxCloth::setCollisionPlanes()</em> function.</p> +<p>Finally, triangles are added using the <em>PxCloth::setCollisionTriangles()</em> function. For example, the following code adds a tetrahedron made of four triangles:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxClothCollisionTriangle</span> <span class="n">triangles</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> + <span class="n">PxClothCollisionTriangle</span><span class="p">(</span><span class="n">PxVec3</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="n">PxVec3</span><span class="p">(</span><span class="mf">1.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="n">PxVec3</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="mf">0.0f</span><span class="p">)),</span> + <span class="n">PxClothCollisionTriangle</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.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="n">PxVec3</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">PxVec3</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="mf">0.0f</span><span class="p">)),</span> + <span class="n">PxClothCollisionTriangle</span><span class="p">(</span><span class="n">PxVec3</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">PxVec3</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="n">PxVec3</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="mf">0.0f</span><span class="p">)),</span> + <span class="n">PxClothCollisionTriangle</span><span class="p">(</span><span class="n">PxVec3</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="n">PxVec3</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">PxVec3</span><span class="p">(</span><span class="mf">1.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="p">};</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The snippet adds collision convex and capsule once in the <em>createCloth</em> function, and then updates collision spheres, planes and triangles every frame in the <em>stepPhysics</em> function.</p> +</div> +</div> +<div class="section" id="adding-virtual-particles"> +<span id="vpsnippet"></span><h3>Adding Virtual Particles<a class="headerlink" href="#adding-virtual-particles" title="Permalink to this headline">¶</a></h3> +<div class="figure align-center"> +<img alt="../_images/ClothVirtualParticles.png" src="../_images/ClothVirtualParticles.png" /> +<p class="caption">Figure 9. Four virtual particles (green) expressed as the weighted combination of a triangle's particles, virtual particles provide a better sampling of the cloth geometry that improves collision detection.</p> +</div> +<p>A virtual particle is defined by 3 particle indices and an index into a weights table, the weights table defines the barycentric coordinates used to create a virtual particle position from a linear combination of the referenced particles. The following is an example weights table that can be used to create a distribution of 4 virtual particles on a triangle:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">PxVec3</span> <span class="n">weights</span><span class="p">[]</span> <span class="o">=</span> +<span class="p">{</span> + <span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.0f</span> <span class="o">/</span> <span class="mi">3</span><span class="p">,</span> <span class="mf">1.0f</span> <span class="o">/</span> <span class="mi">3</span><span class="p">,</span> <span class="mf">1.0f</span> <span class="o">/</span> <span class="mi">3</span><span class="p">),</span> <span class="c1">// center point</span> + <span class="n">PxVec3</span><span class="p">(</span><span class="mf">4.0f</span> <span class="o">/</span> <span class="mi">6</span><span class="p">,</span> <span class="mf">1.0f</span> <span class="o">/</span> <span class="mi">6</span><span class="p">,</span> <span class="mf">1.0f</span> <span class="o">/</span> <span class="mi">6</span><span class="p">),</span> <span class="c1">// off-center point</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The code below shows an example of how to set up the virtual particles from a <em>PxClothMeshDesc</em>:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="n">numFaces</span> <span class="o">=</span> <span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">count</span><span class="p">;</span> +<span class="n">assert</span><span class="p">(</span><span class="n">meshDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">&</span> <span class="n">PxMeshFlag</span><span class="o">::</span><span class="n">e16_BIT_INDICES</span><span class="p">);</span> +<span class="n">PxU8</span><span class="o">*</span> <span class="n">triangles</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxU8</span><span class="o">*</span><span class="p">)</span><span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">data</span><span class="p">;</span> + +<span class="n">PxU32</span> <span class="n">indices</span><span class="p">[]</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxU32</span><span class="p">[</span><span class="mi">4</span><span class="o">*</span><span class="mi">4</span><span class="o">*</span><span class="n">numFaces</span><span class="p">];</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="o">*</span><span class="n">it</span> <span class="o">=</span> <span class="n">indices</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">numFaces</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">PxU16</span><span class="o">*</span> <span class="n">triangle</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxU16</span><span class="o">*</span><span class="p">)</span><span class="n">triangles</span><span class="p">;</span> + <span class="n">PxU32</span> <span class="n">v0</span> <span class="o">=</span> <span class="n">triangle</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> + <span class="n">PxU32</span> <span class="n">v1</span> <span class="o">=</span> <span class="n">triangle</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> + <span class="n">PxU32</span> <span class="n">v2</span> <span class="o">=</span> <span class="n">triangle</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span> + + <span class="c1">// center</span> + <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v0</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v1</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v2</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + + <span class="c1">// off centers</span> + <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v0</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v1</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v2</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> + <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v1</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v2</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v0</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> + <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v2</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v0</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="n">v1</span><span class="p">;</span> <span class="o">*</span><span class="n">it</span><span class="o">++</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> + + <span class="n">triangles</span> <span class="o">+=</span> <span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">stride</span><span class="p">;</span> +<span class="p">}</span> + +<span class="n">cloth</span><span class="p">.</span><span class="n">setVirtualParticles</span><span class="p">(</span><span class="n">numFaces</span><span class="o">*</span><span class="mi">4</span><span class="p">,</span> <span class="n">indices</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">weights</span><span class="p">);</span> +<span class="k">delete</span><span class="p">[]</span> <span class="n">indices</span><span class="p">;</span> +</pre></div> +</div> +</div> +<div class="section" id="accessing-particle-data"> +<h3>Accessing Particle Data<a class="headerlink" href="#accessing-particle-data" title="Permalink to this headline">¶</a></h3> +<p>The cloth snippet doesn't render the result of the simulation, and therefore doesn't read back any particle data. The <em>lockParticleData()</em> provides read and optionally write access to the particle positions of the current and previous iteration. As an example, the following code applies some external acceleration to each particle, similar to <em>setParticleAccelerations()</em>:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxClothParticleData</span><span class="o">*</span> <span class="n">data</span> <span class="o">=</span> <span class="n">cloth</span><span class="p">.</span><span class="n">lockParticleData</span><span class="p">(</span><span class="n">PxDataAccessFlag</span><span class="o">::</span><span class="n">eWRITABLE</span><span class="p">);</span> +<span class="kt">float</span> <span class="n">dt</span> <span class="o">=</span> <span class="n">cloth</span><span class="p">.</span><span class="n">getPreviousTimeStep</span><span class="p">();</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">n</span> <span class="o">=</span> <span class="n">cloth</span><span class="p">.</span><span class="n">getNbParticles</span><span class="p">();</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">data</span><span class="o">-></span><span class="n">previousParticles</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">pos</span> <span class="o">-=</span> <span class="n">particleAccelations</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*</span> <span class="n">dt</span><span class="p">;</span> +<span class="p">}</span> +<span class="n">data</span><span class="o">-></span><span class="n">unlock</span><span class="p">();</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="references"> +<h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> +<p>[1] Mueller, Matthias and Heidelberger, Bruno and Hennix, Marcus and Ratcliff, John. Position based dynamics. Academic Press, Inc.. p. 109--118 2007 <a class="reference external" href="http://dx.doi.org/10.1016/j.jvcir.2007.01.005">http://dx.doi.org/10.1016/j.jvcir.2007.01.005</a></p> +<p>[2] Kim, Tae-Yong and Chentanez, Nuttapong and Mueller-Fischer, Matthias. Long range attachments - a method to simulate inextensible clothing in computer games. Eurographics Association. p. 305--310 2012 <a class="reference external" href="http://dl.acm.org/citation.cfm?id=2422356.2422399">http://dl.acm.org/citation.cfm?id=2422356.2422399</a></p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Cloth</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#simulation-algorithm">Simulation Algorithm</a><ul> +<li><a class="reference internal" href="#solver-frequency">Solver Frequency</a></li> +<li><a class="reference internal" href="#particle-integration">Particle Integration</a></li> +<li><a class="reference internal" href="#local-space-simulation-and-inertia-scale">Local Space Simulation and Inertia Scale</a></li> +<li><a class="reference internal" href="#constraints">Constraints</a></li> +<li><a class="reference internal" href="#distance-constraints">Distance Constraints</a></li> +<li><a class="reference internal" href="#tether-constraints">Tether Constraints</a></li> +<li><a class="reference internal" href="#motion-constraints">Motion Constraints</a></li> +<li><a class="reference internal" href="#separation-constraints">Separation Constraints</a></li> +<li><a class="reference internal" href="#collision-detection">Collision Detection</a></li> +<li><a class="reference internal" href="#continuous-collision-detection">Continuous Collision Detection</a></li> +<li><a class="reference internal" href="#virtual-particle-collision">Virtual Particle Collision</a></li> +<li><a class="reference internal" href="#friction-and-mass-scaling">Friction and Mass Scaling</a></li> +<li><a class="reference internal" href="#self-collision-of-a-single-cloth-actor">Self-Collision of a Single Cloth Actor</a></li> +<li><a class="reference internal" href="#inter-collision-between-multiple-cloth-actors">Inter-Collision between Multiple Cloth Actors</a></li> +</ul> +</li> +<li><a class="reference internal" href="#best-practices-troubleshooting">Best Practices / Troubleshooting</a><ul> +<li><a class="reference internal" href="#performance-tips">Performance Tips</a></li> +<li><a class="reference internal" href="#using-gpu-cloth">Using GPU Cloth</a></li> +<li><a class="reference internal" href="#fast-moving-characters">Fast-Moving Characters</a></li> +<li><a class="reference internal" href="#avoiding-stretching">Avoiding Stretching</a></li> +<li><a class="reference internal" href="#avoiding-jitter">Avoiding Jitter</a></li> +<li><a class="reference internal" href="#pvd-support">PVD Support</a></li> +</ul> +</li> +<li><a class="reference internal" href="#snippet-discussion">Snippet Discussion</a><ul> +<li><a class="reference internal" href="#filling-in-pxclothmeshdesc">Filling in PxClothMeshDesc</a></li> +<li><a class="reference internal" href="#creating-fabric">Creating Fabric</a></li> +<li><a class="reference internal" href="#creating-cloth">Creating Cloth</a></li> +<li><a class="reference internal" href="#specifying-collision-shapes">Specifying Collision Shapes</a></li> +<li><a class="reference internal" href="#adding-virtual-particles">Adding Virtual Particles</a></li> +<li><a class="reference internal" href="#accessing-particle-data">Accessing Particle Data</a></li> +</ul> +</li> +<li><a class="reference internal" href="#references">References</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Particles.html" + title="previous chapter">Particles (deprecated)</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="DebugVisualization.html" + title="next chapter">Debug Visualization</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" /> + <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="DebugVisualization.html" title="Debug Visualization" + >next</a></li> + <li class="right" > + <a href="Particles.html" title="Particles (deprecated)" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/DebugVisualization.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/DebugVisualization.html new file mode 100644 index 00000000..564dfe99 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/DebugVisualization.html @@ -0,0 +1,143 @@ +<!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>Debug Visualization — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="PhysX Visual Debugger (PVD)" href="VisualDebugger.html" /> + <link rel="prev" title="Cloth" href="Cloth.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="VisualDebugger.html" title="PhysX Visual Debugger (PVD)" + accesskey="N">next</a></li> + <li class="right" > + <a href="Cloth.html" title="Cloth" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="debug-visualization"> +<span id="debugvisualization"></span><h1>Debug Visualization<a class="headerlink" href="#debug-visualization" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>With the PhysX Visual Debugger (see <a class="reference internal" href="VisualDebugger.html#physxvisualdebugger"><em>PhysX Visual Debugger (PVD)</em></a>), NVIDIA offers a tool to record information about simulated PhysX scenes and visualize that information in a remote viewer application. However, sometimes it is preferable to integrate visual debug information directly into the application's view. For that purpose, PhysX provides an interface to extract visual debug information as a set of basic rendering primitives, that is, points, lines, triangles and text. These primitives can then be rendered and overlayed with the application render objects.</p> +</div> +<div class="section" id="usage"> +<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2> +<p>To enable debug visualization, the global visualization scale has to be set to a positive value first:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span> <span class="o">=</span> <span class="p">...</span> +<span class="n">scene</span><span class="o">-></span><span class="n">setVisualizationParameter</span><span class="p">(</span><span class="n">PxVisualizationParameter</span><span class="o">::</span><span class="n">eSCALE</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>Then the individual properties that should be visualized can be enabled using, again, a positive value:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">setVisualizationParameter</span><span class="p">(</span><span class="n">PxVisualizationParameter</span><span class="o">::</span><span class="n">eACTOR_AXES</span><span class="p">,</span> <span class="mf">2.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>In the example, the actor world axes will be visualized. The scale used for visualization will be the product of the global scale (1.0 in this example) and the property scale (2.0 in this example). Please note that for some properties the scale factor does not apply: shape geometry, for example, will not be scaled since the size is defined by the user application. Furthermore, for some objects, visualization has to be enabled explicitly on the corresponding object instances too (see <em>PxActorFlag::eVISUALIZATION</em>, <em>PxShapeFlag::eVISUALIZATION</em>, ...).</p> +<p>After a simulation step, the visualization primitives can then be extracted as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxRenderBuffer</span><span class="o">&</span> <span class="n">rb</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">getRenderBuffer</span><span class="p">();</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">rb</span><span class="p">.</span><span class="n">getNbLines</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">const</span> <span class="n">PxDebugLine</span><span class="o">&</span> <span class="n">line</span> <span class="o">=</span> <span class="n">rb</span><span class="p">.</span><span class="n">getLines</span><span class="p">()[</span><span class="n">i</span><span class="p">];</span> + <span class="c1">// render the line</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Do not extract render primitives while the simulation is running.</p> +</div> +<p>The amount of debug visualization data might be too vast to create efficiently for large scenes. In cases where only a localized area is of interest, there is the option to use a culling box for debug visualization via <em>PxScene::setVisualizationCullingBox()</em>.</p> +<p>Note that simply enabling debug visualization (PxVisualizationParameter::eSCALE) can have a significant performance impact, even when all the other individual visualization flags are disabled. Thus, make sure debug visualization is disabled in your final/release builds.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Debug Visualization</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#usage">Usage</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Cloth.html" + title="previous chapter">Cloth</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="VisualDebugger.html" + title="next chapter">PhysX Visual Debugger (PVD)</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" /> + <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="VisualDebugger.html" title="PhysX Visual Debugger (PVD)" + >next</a></li> + <li class="right" > + <a href="Cloth.html" title="Cloth" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/ExtendingSerialization.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/ExtendingSerialization.html new file mode 100644 index 00000000..0cf2419a --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/ExtendingSerialization.html @@ -0,0 +1,430 @@ +<!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>Extending Serialization — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Best Practices Guide" href="BestPractices.html" /> + <link rel="prev" title="Serialization" href="Serialization.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="BestPractices.html" title="Best Practices Guide" + accesskey="N">next</a></li> + <li class="right" > + <a href="Serialization.html" title="Serialization" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="extending-serialization"> +<span id="extendedserialization"></span><h1>Extending Serialization<a class="headerlink" href="#extending-serialization" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>The PhysX serialization system (<a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a>) is extendable to custom types. If an application were to require a new joint type, for example, the serialization system could be extended to add support for serialization of that new joint type.</p> +<p>The following document contains some recipes and example code that show how PhysX serialization may be extended to custom types. It doesn't cover all aspects of the extension mechanisms. It is therefore advisable to look into the following implementation example for more details:</p> +<ul class="simple"> +<li>PhysXVehicle library (PhysXVehicle/src)</li> +</ul> +</div> +<div class="section" id="overview"> +<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2> +<p>Both binary and RepX serialization can be extended for custom types. To prepare the custom type for serialization it must first inherit from <em>PxBase</em>. This allows instances of the custom type to be added to a <em>PxCollection</em>, which is a pre-requisite for serialization. The core serialization functionality needs to be provided by implementing the <em>PxSerializer</em> interface. The template <em>PxSerializerDefaultAdapter</em> provides a default implementation and can be specialized for the custom type as required. In order to support RepX serialization an additional <em>PxRepXSerializer</em> interface needs to be implemented. RepX serialization relies on automatic code generation using clang. Scripts to run the code generation for the examples can be found in (Tools/PhysXMetaDataGenerator).</p> +</div> +<div class="section" id="binary-serialization-of-custom-classes"> +<span id="binaryserializationofcustomclasses"></span><h2>Binary Serialization of Custom Classes<a class="headerlink" href="#binary-serialization-of-custom-classes" title="Permalink to this headline">¶</a></h2> +<p>Serialization and deserialization of a custom class can be achieved with the following steps:</p> +<ol class="arabic simple"> +<li>Define a <em>PxConcreteType</em> and type info for the custom class. Make sure its type value is unique.</li> +<li>The custom class needs to inherit from <em>PxBase</em> and implement it's interface.</li> +<li>Instance PxSerializerDefaultAdapter<T> and implement specialized methods where necessary.</li> +<li>If retargeting to other platforms is needed, implement <em>getBinaryMetaData()</em>.</li> +<li>Register the adapter and metadata, see <em>PX_NEW_SERIALIZER_ADAPTER</em> , <em>PxSerializationRegistry::registerSerializer</em> and <em>PxSerializationRegistry::registerBinaryMetaDataCallback</em>. Note that serializers also need to be unregistered before <em>PxSerializationRegistry::release</em> is called. The application is responsible for custom type serializer allocation and deallocation.</li> +</ol> +<p>For pointer members the following needs to be done (Note that reference members are currently not supported):</p> +<ol class="arabic simple" start="6"> +<li>Implement <em>PxSerializer::requires</em>. It should enumerate <em>PxBase</em> objects on which the object depends for deserialization. See <a class="reference internal" href="Serialization.html#requires"><em>Requires</em></a>.</li> +<li>For a member pointer to another <em>PxBase</em> object, register the reference in the implementation of <em>PxSerializer::registerReferences</em>. The implementation of <em>PxSerializer::requires</em> may be used to help with this.</li> +<li>Resolve references in the implementation of <em>PxSerializer::createObject</em> using <em>PxDeserializationContext::resolveReference, translatePxBase</em>.</li> +<li>Make sure that <em>PxSerializer::isSubordinate</em> returns whether the object can only be serialized along with an owner object. See <a class="reference internal" href="Serialization.html#subordinate"><em>Subordinate</em></a>.</li> +<li>Export non <em>PxBase</em> data by implementing <em>PxSerializer::exportExtraData</em> using <em>PxSerializationContext::writeData, alignData</em>.</li> +<li>Import non <em>PxBase</em> data in the implementation of <em>PxSerializer::createObject</em> using <em>PxDeserializationContext::readExtraData, alignExtraData</em>.</li> +</ol> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">In checked builds (PX_CHECKED defined as 1) metadata definitions are verified against serialized data. If metadata definitions are missing warnings are output on the error stream during re-targeting (<em>PxBinaryConverter::convert</em>). To avoid false warnings, all unused memory in custom serialized class instances should be marked with a 0xcd pattern. This can be done with <em>Cm::markSerializedMem</em> from CmUtils.h.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The memory of a deserialized class instance should not be deallocated. The memory is embedded in the memory buffer containing the serialized data. The flag PxBaseFlag::eOWNS_MEMORY can used to decide whether the object memory needs be deallocated or not.</p> +</div> +<p>Example for a custom class:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "extensions/PxSerialization.h"</span> +<span class="cp">#include "common/PxTypeInfo.h"</span> +<span class="cp">#include "common/PxMetaData.h"</span> +<span class="cp">#include "common/PxSerializer.h"</span> +<span class="cp">#include "common/PxSerialFramework.h</span> + +<span class="k">using</span> <span class="k">namespace</span> <span class="n">physx</span><span class="p">;</span> + +<span class="k">const</span> <span class="n">PxType</span> <span class="n">customClassType</span> <span class="o">=</span> <span class="n">PxConcreteType</span><span class="o">::</span><span class="n">eFIRST_USER_EXTENSION</span><span class="p">;</span> +<span class="n">PX_DEFINE_TYPEINFO</span><span class="p">(</span><span class="n">CustomClass</span><span class="p">,</span> <span class="n">customClassType</span><span class="p">);</span> + +<span class="k">class</span> <span class="nc">CustomClass</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxBase</span> +<span class="p">{</span> + <span class="k">friend</span> <span class="k">class</span> <span class="nc">PxSerializerDefaultAdapter</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">></span><span class="p">;</span> +<span class="nl">public:</span> + + <span class="c1">// constructor setting up PxBase object</span> + <span class="n">CustomClass</span><span class="p">()</span> + <span class="o">:</span> <span class="n">PxBase</span><span class="p">(</span><span class="n">customClassType</span><span class="p">,</span> <span class="n">PxBaseFlag</span><span class="o">::</span><span class="n">eOWNS_MEMORY</span> <span class="o">|</span> <span class="n">PxBaseFlag</span><span class="o">::</span><span class="n">eIS_RELEASABLE</span><span class="p">)</span> + <span class="p">{}</span> + + <span class="c1">// constructor called on deserialization</span> + <span class="n">CustomClass</span><span class="p">(</span><span class="n">PxBaseFlags</span> <span class="n">baseFlags</span><span class="p">)</span> <span class="o">:</span> <span class="n">PxBase</span><span class="p">(</span><span class="n">baseFlags</span><span class="p">)</span> <span class="p">{}</span> + + <span class="k">virtual</span> <span class="o">~</span><span class="n">CustomClass</span><span class="p">()</span> <span class="p">{}</span> + + + <span class="c1">//PxBase</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getConcreteTypeName</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="s">"CustomClass"</span><span class="p">;</span> <span class="p">}</span> + + <span class="k">virtual</span> <span class="kt">bool</span> <span class="n">isKindOf</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">name</span><span class="p">)</span> <span class="k">const</span> + <span class="p">{</span> + <span class="k">return</span> <span class="o">!</span><span class="n">strcmp</span><span class="p">(</span><span class="s">"CustomClass"</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span> <span class="o">||</span> <span class="n">PxBase</span><span class="o">::</span><span class="n">isKindOf</span><span class="p">(</span><span class="n">name</span><span class="p">);</span> + <span class="p">}</span> + <span class="c1">//~PxBase</span> + + <span class="c1">//PxSerializationRegistry::registerBinaryMetaDataCallback</span> + <span class="k">static</span> <span class="kt">void</span> <span class="n">getBinaryMetaData</span><span class="p">(</span><span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">stream</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">PX_DEF_BIN_METADATA_VCLASS</span><span class="p">(</span><span class="n">stream</span><span class="p">,</span> <span class="n">CustomClass</span><span class="p">)</span> + <span class="n">PX_DEF_BIN_METADATA_BASE_CLASS</span><span class="p">(</span><span class="n">stream</span><span class="p">,</span> <span class="n">CustomClass</span><span class="p">,</span> <span class="n">PxBase</span><span class="p">)</span> + + <span class="n">PX_DEF_BIN_METADATA_ITEM</span><span class="p">(</span><span class="n">stream</span><span class="p">,</span> <span class="n">CustomClass</span><span class="p">,</span> <span class="n">PxRigidDynamic</span><span class="p">,</span> <span class="n">mActor</span><span class="p">,</span> + <span class="n">PxMetaDataFlag</span><span class="o">::</span><span class="n">ePTR</span><span class="p">)</span> + <span class="n">PX_DEF_BIN_METADATA_ITEM</span><span class="p">(</span><span class="n">stream</span><span class="p">,</span> <span class="n">CustomClass</span><span class="p">,</span> <span class="kt">char</span><span class="p">,</span> <span class="n">mBuf</span><span class="p">,</span> <span class="n">PxMetaDataFlag</span><span class="o">::</span><span class="n">ePTR</span><span class="p">)</span> + <span class="n">PX_DEF_BIN_METADATA_ITEM</span><span class="p">(</span><span class="n">stream</span><span class="p">,</span> <span class="n">CustomClass</span><span class="p">,</span> <span class="n">PxU32</span><span class="p">,</span> <span class="n">mSize</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> + + <span class="n">PX_DEF_BIN_METADATA_EXTRA_ITEMS</span><span class="p">(</span><span class="n">stream</span><span class="p">,</span> <span class="n">CustomClass</span><span class="p">,</span> <span class="kt">char</span><span class="p">,</span> <span class="n">mBuf</span><span class="p">,</span> <span class="n">mSize</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="p">}</span> + <span class="c1">//~PxSerializationRegistry::registerBinaryMetaDataCallback</span> + +<span class="nl">private:</span> + <span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">mActor</span><span class="p">;</span> <span class="c1">//add in requires</span> + <span class="kt">char</span><span class="o">*</span> <span class="n">mBuf</span><span class="p">;</span> <span class="c1">//extra data</span> + <span class="n">PxU32</span> <span class="n">mSize</span><span class="p">;</span> <span class="c1">//size of mBuf</span> +<span class="p">};</span> + +<span class="c1">//PxSerializerDefaultAdapter</span> +<span class="k">template</span><span class="o"><></span> +<span class="kt">void</span> <span class="n">PxSerializerDefaultAdapter</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">>::</span><span class="n">requires</span><span class="p">(</span><span class="n">PxBase</span><span class="o">&</span> <span class="n">obj</span><span class="p">,</span> + <span class="n">PxProcessPxBaseCallback</span><span class="o">&</span> <span class="n">c</span><span class="p">)</span> <span class="k">const</span> +<span class="p">{</span> + <span class="n">CustomClass</span><span class="o">*</span> <span class="n">custom</span> <span class="o">=</span> <span class="n">obj</span><span class="p">.</span><span class="n">is</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">></span><span class="p">();</span> + <span class="n">PX_ASSERT</span><span class="p">(</span><span class="n">custom</span><span class="p">);</span> + <span class="n">c</span><span class="p">.</span><span class="n">process</span><span class="p">(</span><span class="o">*</span><span class="n">custom</span><span class="o">-></span><span class="n">mActor</span><span class="p">);</span> +<span class="p">}</span> + +<span class="k">template</span><span class="o"><></span> +<span class="kt">void</span> <span class="n">PxSerializerDefaultAdapter</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">>::</span><span class="n">registerReferences</span><span class="p">(</span><span class="n">PxBase</span><span class="o">&</span> <span class="n">obj</span><span class="p">,</span> + <span class="n">PxSerializationContext</span><span class="o">&</span> <span class="n">s</span><span class="p">)</span> <span class="k">const</span> +<span class="p">{</span> + <span class="n">CustomClass</span><span class="o">*</span> <span class="n">custom</span> <span class="o">=</span> <span class="n">obj</span><span class="p">.</span><span class="n">is</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">></span><span class="p">();</span> + <span class="n">PX_ASSERT</span><span class="p">(</span><span class="n">custom</span><span class="p">);</span> + + <span class="n">s</span><span class="p">.</span><span class="n">registerReference</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">PX_SERIAL_REF_KIND_PXBASE</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">(</span><span class="o">&</span><span class="n">obj</span><span class="p">));</span> + <span class="n">s</span><span class="p">.</span><span class="n">registerReference</span><span class="p">(</span><span class="o">*</span><span class="n">custom</span><span class="o">-></span><span class="n">mActor</span><span class="p">,</span> <span class="n">PX_SERIAL_REF_KIND_PXBASE</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">(</span><span class="n">custom</span><span class="o">-></span><span class="n">mActor</span><span class="p">));</span> +<span class="p">}</span> + +<span class="k">template</span><span class="o"><></span> +<span class="kt">void</span> <span class="n">PxSerializerDefaultAdapter</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">>::</span><span class="n">exportExtraData</span><span class="p">(</span><span class="n">PxBase</span><span class="o">&</span> <span class="n">obj</span><span class="p">,</span> + <span class="n">PxSerializationContext</span><span class="o">&</span> <span class="n">s</span><span class="p">)</span> <span class="k">const</span> +<span class="p">{</span> + <span class="n">CustomClass</span><span class="o">*</span> <span class="n">custom</span> <span class="o">=</span> <span class="n">obj</span><span class="p">.</span><span class="n">is</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">></span><span class="p">();</span> + <span class="n">PX_ASSERT</span><span class="p">(</span><span class="n">custom</span><span class="p">);</span> + <span class="n">s</span><span class="p">.</span><span class="n">alignData</span><span class="p">(</span><span class="n">PX_SERIAL_ALIGN</span><span class="p">);</span> + <span class="n">s</span><span class="p">.</span><span class="n">writeData</span><span class="p">(</span><span class="n">custom</span><span class="o">-></span><span class="n">mBuf</span><span class="p">,</span> <span class="n">custom</span><span class="o">-></span><span class="n">mSize</span><span class="p">);</span> +<span class="p">}</span> + +<span class="k">template</span><span class="o"><></span> +<span class="n">PxBase</span><span class="o">*</span> <span class="n">PxSerializerDefaultAdapter</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">>::</span><span class="n">createObject</span><span class="p">(</span><span class="n">PxU8</span><span class="o">*&</span> <span class="n">address</span><span class="p">,</span> + <span class="n">PxDeserializationContext</span><span class="o">&</span> <span class="n">context</span><span class="p">)</span> + <span class="k">const</span> +<span class="p">{</span> + <span class="n">CustomClass</span><span class="o">*</span> <span class="n">custom</span> <span class="o">=</span> <span class="k">new</span> <span class="p">(</span><span class="n">address</span><span class="p">)</span> <span class="n">CustomClass</span><span class="p">(</span><span class="n">PxBaseFlag</span><span class="o">::</span><span class="n">eIS_RELEASABLE</span><span class="p">);</span> + <span class="n">address</span> <span class="o">+=</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">CustomClass</span><span class="p">);</span> + + <span class="c1">// resolve references</span> + <span class="n">context</span><span class="p">.</span><span class="n">translatePtr</span><span class="p">(</span><span class="n">custom</span><span class="o">-></span><span class="n">mActor</span><span class="p">);</span> + + <span class="c1">// import extra data</span> + <span class="n">custom</span><span class="o">-></span><span class="n">mBuf</span> <span class="o">=</span> <span class="n">context</span><span class="p">.</span><span class="n">readExtraData</span><span class="o"><</span><span class="kt">char</span><span class="o">*</span><span class="p">,</span> <span class="n">PX_SERIAL_ALIGN</span><span class="o">></span><span class="p">();</span> + + <span class="c1">// return deserialized object</span> + <span class="k">return</span> <span class="n">custom</span><span class="p">;</span> +<span class="p">}</span> +<span class="c1">//~PxSerializerDefaultAdapter</span> + +<span class="kt">void</span> <span class="n">registerCustomClassBinarySerializer</span><span class="p">(</span><span class="n">PxSerializationRegistry</span><span class="o">&</span> <span class="n">registry</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">registry</span><span class="p">.</span><span class="n">registerSerializer</span><span class="p">(</span><span class="n">customClassType</span><span class="p">,</span> <span class="n">PX_NEW_SERIALIZER_ADAPTER</span><span class="p">(</span><span class="n">CustomClass</span><span class="p">));</span> + <span class="n">registry</span><span class="p">.</span><span class="n">registerBinaryMetaDataCallback</span><span class="p">(</span><span class="n">CustomClass</span><span class="o">::</span><span class="n">getBinaryMetaData</span><span class="p">);</span> +<span class="p">}</span> + +<span class="kt">void</span> <span class="n">unregisterCustomClassBinarySerializer</span><span class="p">(</span><span class="n">PxSerializationRegistry</span><span class="o">&</span> <span class="n">registry</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PX_DELETE_SERIALIZER_ADAPTER</span><span class="p">(</span><span class="n">registry</span><span class="p">.</span><span class="n">unregisterSerializer</span><span class="p">(</span><span class="n">customClassType</span><span class="p">));</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="repx-serialization-of-custom-classes"> +<h2>RepX Serialization of Custom Classes<a class="headerlink" href="#repx-serialization-of-custom-classes" title="Permalink to this headline">¶</a></h2> +<p>Serialization and deserialization of a custom class can be achieved with the following steps:</p> +<ol class="arabic simple"> +<li>Perform the first three steps from <a class="reference internal" href="#binaryserializationofcustomclasses"><em>Binary Serialization of Custom Classes</em></a>. Methods in <em>PxSerializer</em> and <em>PxSerializerDefaultAdapter<T></em> required exclusively for binary serialization may be left empty.</li> +<li>Create a custom RepX serializer that implements the <em>PxRepXSerializer</em> interface. <em>PxRepXSerializer</em> is used to create an object from the xml file and write an object to the xml file. The class <em>RepXSerializerImpl</em> can be used to inherit default implementations of some methods.</li> +<li>Register the general serializer adapter and the RepX serializer. Note that custom type serializers also need to be unregistered and deallocated.</li> +<li>RepX supports automatic reading and writing of class properties. To achieve this, clang has to be used to generate corresponding metadata: <a class="reference internal" href="#physxmetadata"><em>PhysX API Metadata System</em></a>.</li> +</ol> +<p>Example for a custom class:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "SnRepXSerializerImpl.h"</span> + +<span class="k">const</span> <span class="n">PxType</span> <span class="n">customClassType</span> <span class="o">=</span> <span class="n">PxConcreteType</span><span class="o">::</span><span class="n">eFIRST_USER_EXTENSION</span><span class="p">;</span> +<span class="n">PX_DEFINE_TYPEINFO</span><span class="p">(</span><span class="n">CustomClass</span><span class="p">,</span> <span class="n">customClassType</span><span class="p">);</span> + +<span class="k">struct</span> <span class="n">CustomClassRepXSerializer</span> <span class="o">:</span> <span class="k">public</span> <span class="n">RepXSerializerImpl</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">></span> +<span class="p">{</span> + <span class="n">CustomClassRepXSerializer</span><span class="p">(</span><span class="n">PxAllocatorCallback</span><span class="o">&</span> <span class="n">inCallback</span><span class="p">)</span> + <span class="o">:</span> <span class="n">RepXSerializerImpl</span><span class="o"><</span><span class="n">CustomClass</span><span class="o">></span><span class="p">(</span><span class="n">inCallback</span><span class="p">)</span> + <span class="p">{}</span> + + <span class="k">virtual</span> <span class="n">PxRepXObject</span> <span class="n">fileToObject</span><span class="p">(</span><span class="n">XmlReader</span><span class="o">&</span> <span class="n">inReader</span><span class="p">,</span> <span class="n">XmlMemoryAllocator</span><span class="o">&</span> <span class="n">inAllocator</span><span class="p">,</span> + <span class="n">PxRepXInstantiationArgs</span><span class="o">&</span> <span class="n">inArgs</span><span class="p">,</span> <span class="n">PxCollection</span><span class="o">*</span> <span class="n">inCollection</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// factory for CustomClass instance provided by application</span> + <span class="n">CustomClass</span><span class="o">*</span> <span class="n">object</span> <span class="o">=</span> <span class="n">createCustomClass</span><span class="p">();</span> + + <span class="c1">// when using the PhysX API metadata system readAllProperties(...) can be used to read</span> + <span class="c1">// all properties automatically</span> + <span class="n">readAllProperties</span><span class="p">(</span><span class="n">inArgs</span><span class="p">,</span> <span class="n">inReader</span><span class="p">,</span> <span class="n">object</span><span class="p">,</span> <span class="n">inAllocator</span><span class="p">,</span> <span class="o">*</span><span class="n">inCollection</span><span class="p">);</span> + + <span class="k">return</span> <span class="nf">PxCreateRepXObject</span><span class="p">(</span><span class="n">object</span><span class="p">);</span> + <span class="p">}</span> + + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">objectToFileImpl</span><span class="p">(</span><span class="k">const</span> <span class="n">CustomClass</span><span class="o">*</span> <span class="n">obj</span><span class="p">,</span> <span class="n">PxCollection</span><span class="o">*</span> <span class="n">inCollection</span><span class="p">,</span> + <span class="n">XmlWriter</span><span class="o">&</span> <span class="n">inWriter</span><span class="p">,</span> <span class="n">MemoryBuffer</span><span class="o">&</span> <span class="n">inTempBuffer</span><span class="p">,</span> + <span class="n">PxRepXInstantiationArgs</span><span class="o">&</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// when using the PhysX API metadata system writeAllProperties(...) can be used to save</span> + <span class="c1">// all properties automatically</span> + <span class="n">writeAllProperties</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">inWriter</span><span class="p">,</span> <span class="n">inTempBuffer</span><span class="p">,</span> <span class="o">*</span><span class="n">inCollection</span><span class="p">);</span> + <span class="p">}</span> + + <span class="c1">// this can return NULL if fileToObject(...) is overwritten with a custom implementation.</span> + <span class="k">virtual</span> <span class="n">CustomClass</span><span class="o">*</span> <span class="n">allocateObject</span><span class="p">(</span><span class="n">PxRepXInstantiationArgs</span><span class="o">&</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> <span class="p">}</span> +<span class="p">};</span> + +<span class="kt">void</span> <span class="nf">registerCustomClassRepXSerializer</span><span class="p">(</span><span class="n">PxSerializationRegistry</span><span class="o">&</span> <span class="n">registry</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">registry</span><span class="p">.</span><span class="n">registerSerializer</span><span class="p">(</span><span class="n">customClassType</span><span class="p">,</span> + <span class="n">PX_NEW_SERIALIZER_ADAPTER</span><span class="p">(</span><span class="n">CustomClass</span><span class="p">));</span> + + <span class="n">registry</span><span class="p">.</span><span class="n">registerRepXSerializer</span><span class="p">(</span><span class="n">customClassType</span><span class="p">,</span> + <span class="n">PX_NEW_REPX_SERIALIZER</span><span class="o"><</span><span class="n">CustomClassRepXSerializer</span><span class="o">></span><span class="p">));</span> +<span class="p">}</span> + +<span class="kt">void</span> <span class="nf">unregisterCustomClassRepXSerializer</span><span class="p">(</span><span class="n">PxSerializationRegistry</span><span class="o">&</span> <span class="n">registry</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PX_DELETE_SERIALIZER_ADAPTER</span><span class="p">(</span><span class="n">registry</span><span class="p">.</span><span class="n">unregisterSerializer</span><span class="p">(</span><span class="n">customClassType</span><span class="p">));</span> + <span class="n">PX_DELETE_REPX_SERIALIZER</span><span class="p">(</span><span class="n">registry</span><span class="p">.</span><span class="n">unregisterRepXSerializer</span><span class="p">(</span><span class="n">customClassType</span><span class="p">));</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Implementing a PxRepXSerializer is currently not practical without including the internal PhysXExtension header "SnRepXSerializerImpl.h".</p> +</div> +<div class="section" id="physx-api-metadata-system"> +<span id="physxmetadata"></span><h3>PhysX API Metadata System<a class="headerlink" href="#physx-api-metadata-system" title="Permalink to this headline">¶</a></h3> +<p>This system produces a set of objects that are analogues of the interfaces and of descriptors in the PhysX system, all based on the public interface. The generator heuristically finds functions that start with get/set and, through a series of cascading rules, combines those into several types of properties.</p> +<p>Currently the generator supports the following property types:</p> +<ul class="simple"> +<li>Basic property<ul> +<li>{ptype} get{pname}() const;</li> +<li>void set{pname}( const ptype& prop ); //plus variations</li> +<li>read-only, write-only variants of above.</li> +</ul> +</li> +<li>Range property<ul> +<li>void get{pname}( {ptype}& lowEnd, {ptype}& highEnd );</li> +<li>void set{pname}( {ptype} lowEnd, {ptype} highEnd );</li> +</ul> +</li> +<li>Indexed property<ul> +<li>{ptype} get{pname}( enumType idx );</li> +<li>void set{pname}( enumType idx, const {ptype}& prop );</li> +</ul> +</li> +<li>Dual indexed property (like above, but with two enumeration indexes).</li> +<li>Collection<ul> +<li>PxU32 getNb() const;</li> +<li>PxU32 get( {ptype}* buffer, PxU32 count );</li> +<li>void set({ptype}* buffer, PxU32 count);</li> +</ul> +</li> +</ul> +<p>In order to make use of the generator the following files need to be created with the following recipe:</p> +<ul> +<li><p class="first">CustomTypeExtensionAPI.h</p> +<ul class="simple"> +<li>Add all the types that should be exported to gUserPhysXTypes to this file.</li> +<li>Add the unnecessary types to gAvoidedPhysXTypes. It will not generate metadata information for these types.</li> +<li>Be sure to append the included files for these types.</li> +</ul> +</li> +<li><p class="first">runClang_[windows|osx|linux].[bat|sh] (e.g. runClang_windows.bat)</p> +<ul> +<li><p class="first">Set definition folder for these autogenerated files and set the source file in here.</p> +</li> +<li><p class="first">Specify the filename of autogenerated files. Then it will generate the following files:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">include</span><span class="o">/</span><span class="n">CustomTypeAutoGeneratedMetaDataObjectNames</span><span class="p">.</span><span class="n">h</span> +<span class="n">include</span><span class="o">/</span><span class="n">CustomTypeAutoGeneratedMetaDataObjects</span><span class="p">.</span><span class="n">h</span> +<span class="n">src</span><span class="o">/</span><span class="n">CustomTypeAutoGeneratedMetaDataObjects</span><span class="p">.</span><span class="n">cpp</span> +</pre></div> +</div> +</li> +</ul> +</li> +<li><p class="first">CustomTypeMetaDataObjects.h</p> +<ul class="simple"> +<li>CustomTypePropertyInfoName has to be defined and CustomTypeAutoGeneratedMetaDataObjects.h has to be included in this file. The file will then export the properties of the custom class and can be included for implementing the custom RepX serializer.</li> +</ul> +</li> +<li><p class="first">CustomTypeMetaDataObjects.cpp</p> +<ul class="simple"> +<li>This file is optional. It is only required when custom properties are needed.</li> +</ul> +</li> +</ul> +<p>PxVehicle serialization is a useful example. With Source/PhysXVehicle as the root folder the structure of the files is as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">src</span><span class="o">/</span><span class="n">PhysXMetaData</span><span class="o">/</span><span class="n">include</span><span class="o">/</span><span class="n">PxVehicleMetaDataObjects</span><span class="p">.</span><span class="n">h</span> +<span class="n">src</span><span class="o">/</span><span class="n">PhysXMetaData</span><span class="o">/</span><span class="n">src</span><span class="o">/</span><span class="n">PxVehicleMetaDataObjects</span><span class="p">.</span><span class="n">cpp</span> +<span class="p">..</span><span class="o">/</span><span class="p">..</span><span class="o">/</span><span class="n">Tools</span><span class="o">/</span><span class="n">PhysXMetaDataGenerator</span><span class="o">/</span><span class="n">PxVehicleExtension</span><span class="o">/</span><span class="n">PxVehicleExtensionAPI</span><span class="p">.</span><span class="n">h</span> +<span class="p">..</span><span class="o">/</span><span class="p">..</span><span class="o">/</span><span class="n">Tools</span><span class="o">/</span><span class="n">PhysXMetaDataGenerator</span><span class="o">/</span><span class="n">PxVehicleExtension</span><span class="o">/</span><span class="n">runClang_</span><span class="p">[</span><span class="n">windows</span><span class="o">|</span><span class="n">osx</span><span class="o">|</span><span class="n">linux</span><span class="p">].[</span><span class="n">bat</span><span class="o">|</span><span class="n">sh</span><span class="p">]</span> +</pre></div> +</div> +<p>Running the script will auto-generate the following files:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">src</span><span class="o">/</span><span class="n">PhysXMetaData</span><span class="o">/</span><span class="n">include</span><span class="o">/</span><span class="n">PxVehicleAutoGeneratedMetaDataObjectNames</span><span class="p">.</span><span class="n">h</span> +<span class="n">src</span><span class="o">/</span><span class="n">PhysXMetaData</span><span class="o">/</span><span class="n">include</span><span class="o">/</span><span class="n">PxVehicleAutoGeneratedMetaDataObjects</span><span class="p">.</span><span class="n">h</span> +<span class="n">src</span><span class="o">/</span><span class="n">PhysXMetaData</span><span class="o">/</span><span class="n">src</span><span class="o">/</span><span class="n">PxVehicleAutoGeneratedMetaDataObjects</span><span class="p">.</span><span class="n">cpp</span> +</pre></div> +</div> +<ol class="arabic simple"> +<li>PxVehicleExtensionAPI.h: The type DisabledPropertyEntry is used to mark properties which do not require export. CustomProperty is for properties that need to be customized and gUserPhysXTypes is for general properties that need to be exported.</li> +<li>runClang_[windows|osx|linux].[bat|sh]: The target directory is set to src/PhysXMetaData, and the target name is PxVehicle.</li> +<li>PxVehicleMetaDataObjects.h: It defines the custom properties and includes PxVehicleAutoGeneratedMetaDataObjects.h</li> +<li>PxVehicleMetaDataObjects.cpp: It implements the custom properties.</li> +</ol> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The properties defined in PxVehicleAutoGeneratedMetaDataObjects.h are written to the RepX file automatically if PxVehicleMetaDataObjects.h is included for the custom RepX serializer.</p> +</div> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Extending Serialization</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#overview">Overview</a></li> +<li><a class="reference internal" href="#binary-serialization-of-custom-classes">Binary Serialization of Custom Classes</a></li> +<li><a class="reference internal" href="#repx-serialization-of-custom-classes">RepX Serialization of Custom Classes</a><ul> +<li><a class="reference internal" href="#physx-api-metadata-system">PhysX API Metadata System</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Serialization.html" + title="previous chapter">Serialization</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="BestPractices.html" + title="next chapter">Best Practices Guide</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" /> + <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="BestPractices.html" title="Best Practices Guide" + >next</a></li> + <li class="right" > + <a href="Serialization.html" title="Serialization" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/GPURigidBodies.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/GPURigidBodies.html new file mode 100644 index 00000000..1a750221 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/GPURigidBodies.html @@ -0,0 +1,216 @@ +<!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>GPU Rigid Bodies — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Geometry Queries" href="GeometryQueries.html" /> + <link rel="prev" title="Scene Origin" href="OriginShift.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="GeometryQueries.html" title="Geometry Queries" + accesskey="N">next</a></li> + <li class="right" > + <a href="OriginShift.html" title="Scene Origin" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="gpu-rigid-bodies"> +<span id="gpurigidbodies"></span><h1>GPU Rigid Bodies<a class="headerlink" href="#gpu-rigid-bodies" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>GPU Rigid Bodies is a new feature introduced in PhysX 3.4. It supports the entire rigid body pipeline feature-set but currently does not support articulations. The state of GPU-accelerated rigid bodies can be modified and queried using the exact same API as used to modify and query CPU rigid bodies. GPU rigid bodies can interact with clothing and particles in the same way that CPU rigid bodies can and can easily be used in conjunction with character controllers (CCTs) and vehicles.</p> +</div> +<div class="section" id="using-gpu-rigid-bodies"> +<h2>Using GPU Rigid Bodies<a class="headerlink" href="#using-gpu-rigid-bodies" title="Permalink to this headline">¶</a></h2> +<p>GPU rigid bodies are no more difficult to use than CPU rigid bodies. GPU rigid bodies use the exact same API and same classes as CPU rigid bodies. GPU rigid body acceleration is enabled on a per-scene basis. If enabled, all rigid bodies occupying the scene will be processed by the GPU. This feature is implemented in CUDA and requires SM3.0 (Kepler) or later compatible GPU. If no compatible device is found, simulation will fall back onto the CPU and corresponding error messages will be provided.</p> +<p>This feature is split into two components: rigid body dynamics and broad phase. These are enabled using PxSceneFlag::eENABLE_GPU_DYNAMICS and by setting PxSceneDesc::broadphaseType to PxBroadPhaseType::eGPU respectively. These properties are immutable properties of the scene. In addition, you must initialize the CUDA context manager and set the GPU dispatcher on the PxSceneDesc. This is also a requirement to make use of GPU-accelerated particles or clothing. A snippet demonstrating how to enable GPU rigid body simulation is provided in SnippetHelloGRB. The code example below serves as a brief reference:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxCudaContextManagerDesc</span> <span class="n">cudaContextManagerDesc</span><span class="p">;</span> + +<span class="n">gCudaContextManager</span> <span class="o">=</span> <span class="n">PxCreateCudaContextManager</span><span class="p">(</span><span class="o">*</span><span class="n">gFoundation</span><span class="p">,</span> <span class="n">cudaContextManagerDesc</span><span class="p">);</span> + +<span class="n">PxSceneDesc</span> <span class="nf">sceneDesc</span><span class="p">(</span><span class="n">gPhysics</span><span class="o">-></span><span class="n">getTolerancesScale</span><span class="p">());</span> +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">gravity</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.81f</span><span class="p">,</span> <span class="mf">0.0f</span><span class="p">);</span> +<span class="n">gDispatcher</span> <span class="o">=</span> <span class="n">PxDefaultCpuDispatcherCreate</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span> +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">cpuDispatcher</span> <span class="o">=</span> <span class="n">gDispatcher</span><span class="p">;</span> +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">filterShader</span> <span class="o">=</span> <span class="n">PxDefaultSimulationFilterShader</span><span class="p">;</span> +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">gpuDispatcher</span> <span class="o">=</span> <span class="n">gCudaContextManager</span><span class="o">-></span><span class="n">getGpuDispatcher</span><span class="p">();</span> + +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">|=</span> <span class="n">PxSceneFlag</span><span class="o">::</span><span class="n">eENABLE_GPU_DYNAMICS</span><span class="p">;</span> +<span class="n">sceneDesc</span><span class="p">.</span><span class="n">broadPhaseType</span> <span class="o">=</span> <span class="n">PxBroadPhaseType</span><span class="o">::</span><span class="n">eGPU</span><span class="p">;</span> + +<span class="n">gScene</span> <span class="o">=</span> <span class="n">gPhysics</span><span class="o">-></span><span class="n">createScene</span><span class="p">(</span><span class="n">sceneDesc</span><span class="p">);</span> +</pre></div> +</div> +<p>Enabling GPU rigid body dynamics turns on GPU-accelerated contact generation, shape/body management and the GPU-accelerated constraint solver. This accelerates the majority of the discrete rigid body pipeline.</p> +<p>Turning on GPU broad phase replaces the CPU broad phase with a GPU-accelerated broad phase.</p> +<p>Each can be enabled independently so, for example, you may enable GPU broad phase with CPU rigid body dynamics , CPU broad phase (either SAP or MBP) with GPU rigid body dynamics or combine GPU broad phase with GPU rigid body dynamics.</p> +</div> +<div class="section" id="what-is-gpu-accelerated"> +<h2>What is GPU accelerated?<a class="headerlink" href="#what-is-gpu-accelerated" title="Permalink to this headline">¶</a></h2> +<p>The GPU rigid body feature provides GPU-accelerated implementations of:</p> +<ul class="simple"> +<li>Broad Phase</li> +<li>Contact generation</li> +<li>Shape and body management</li> +<li>Constraint solver</li> +</ul> +<p>All other features are performed on the CPU.</p> +<p>There are several caveats to GPU contact generation. These are as follows:</p> +<ul class="simple"> +<li>GPU contact generation supports only boxes, convex hulls, triangle meshes and heightfields. Any spheres, capsules or planes will have contact generation involving those shapes processed on the CPU, rather than GPU.</li> +<li>Convex hulls require PxCookingParam::buildGRBData to be set to true to build data required to perform contact generation on the GPU. If a hull with more than 64 vertices or more than 32 vertices per-face is used, it will be processed on the CPU. If the PxConvexFlag::eGPU_COMPATIBLE flag is used when the convex hull is created the limits are applied to ensure the resulting hull can be used on GPU.</li> +<li>Triangle meshes require PxCookingParam::buildGRBData to be set to true to build data required to process the mesh on the GPU. If this flag is not set during cooking, the GPU data for the mesh will be absent and any contact generation involving this mesh will be processed on CPU.</li> +<li>Any pairs requesting contact modification will be processed on the CPU.</li> +<li>PxSceneFlag::eENABLE_PCM must be enabled for GPU contact generation to be performed. This is the only form of contact generation implemented on the GPU. If eENABLE_PCM is not raised, contact generation will be processed on CPU for all pairs using the non distance-based legacy contact generation.</li> +</ul> +<p>Irrespective of whether contact generation for a given pair is processed on CPU or GPU, the GPU solver will process all pairs with contacts that request collision response in their filter shader.</p> +<p>As mentioned above, GPU rigid bodies currently do not support articulations. If eENABLE_GPU_DYNAMICS is enabled on the scene, any attempts to add an articulation to the scene will result in an error message being displayed and the articulation will not be added to the scene.</p> +<p>The GPU rigid body solver provides full support for joints and contacts. However, best performance is achieved using D6 joints because D6 joints are natively supported on the GPU, i.e. the full solver pipeline from prep to solve is implemented on the GPU. Other joint types are supported by the GPU solver but their joint shaders are run on the CPU. This will incur some additional host-side performance overhead compared to D6 joints.</p> +</div> +<div class="section" id="tuning"> +<h2>Tuning<a class="headerlink" href="#tuning" title="Permalink to this headline">¶</a></h2> +<p>Unlike CPU PhysX, the GPU rigid bodies feature is not able to dynamically grow all buffers. Therefore, it is necessary to provide some fixed buffer sizes for the GPU rigid body feature. If insufficient memory is available, the system will issue warnings and discard contacts/constraints/pairs, which means that behavior may be adversely affected. The following buffers are adjustable in PxSceneDesc::gpuDynamicsConfig:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">PxgDynamicsMemoryConfig</span> +<span class="p">{</span> + <span class="n">PxU32</span> <span class="n">constraintBufferCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of constraint buffer allocated in GPU global memory</span> + <span class="n">PxU32</span> <span class="n">contactBufferCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of contact buffer allocated in GPU global memory</span> + <span class="n">PxU32</span> <span class="n">tempBufferCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of temp buffer allocated in pinned host memory.</span> + <span class="n">PxU32</span> <span class="n">contactStreamCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of contact stream buffer allocated in pinned host memory. This is double-buffered so total allocation size = 2* contactStreamCapacity.</span> + <span class="n">PxU32</span> <span class="n">patchStreamCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of the contact patch stream buffer allocated in pinned host memory. This is double-buffered so total allocation size = 2 * patchStreamCapacity.</span> + <span class="n">PxU32</span> <span class="n">forceStreamCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of force buffer allocated in pinned host memory.</span> + <span class="n">PxU32</span> <span class="n">heapCapacity</span><span class="p">;</span> <span class="c1">//!< Initial capacity of the GPU and pinned host memory heaps. Additional memory will be allocated if more memory is required.</span> + <span class="n">PxU32</span> <span class="n">foundLostPairsCapacity</span><span class="p">;</span> <span class="c1">//!< Capacity of found and lost buffers allocated in GPU global memory. This is used for the found/lost pair reports in the BP.</span> + + + <span class="n">PxgDynamicsMemoryConfig</span><span class="p">()</span> <span class="o">:</span> + <span class="n">constraintBufferCapacity</span><span class="p">(</span><span class="mi">32</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">contactBufferCapacity</span><span class="p">(</span><span class="mi">24</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">tempBufferCapacity</span><span class="p">(</span><span class="mi">16</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">contactStreamCapacity</span><span class="p">(</span><span class="mi">6</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">patchStreamCapacity</span><span class="p">(</span><span class="mi">5</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">forceStreamCapacity</span><span class="p">(</span><span class="mi">1</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">heapCapacity</span><span class="p">(</span><span class="mi">64</span> <span class="o">*</span> <span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">),</span> + <span class="n">foundLostPairsCapacity</span><span class="p">(</span><span class="mi">256</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">)</span> + <span class="p">{</span> + <span class="p">}</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The default values are generally sufficient for scenes simulating approximately 10,000 rigid bodies.</p> +<ul class="simple"> +<li>constraintBufferCapacity defines the total amount of memory that can be occupied by constraints in the solver. If more memory is required, a warning is issued and no further constraints will be created.</li> +<li>contactBufferCapacity defines the size of a temporary contact buffer used in the constraint solver. If more memory is required, a warning is issued and contacts will be dropped.</li> +<li>tempBufferCapacity defines the size of a buffer used for miscellaneous transient memory allocations used in the constraint solver.</li> +<li>contactStreamCapacity defines the size of a buffer used to store contacts in the contact stream. This data is allocated in pinned host memory and is double-buffered. If insufficient memory is allocated, a warning will be issued and contacts will be dropped.</li> +<li>patchStreamCapacity defines the size of a buffer used to store contact patches in the contact stream. This data is allocated in pinned host memory and is double-buffered. If insufficient memory is allocated, a warning will be issued and contacts will be dropped.</li> +<li>forceStreamCapacity defines the size of a buffer used to report applied contact forces to the user. This data is allocated in pinned host memory. If insufficient memory is allocated, a warning will be issued and contacts will be dropped.</li> +<li>heapCapacity defines the initial size of the GPU and pinned host memory heaps. Additional memory will be allocated if more memory is required. The cost of physically allocating memory can be relatively high so a custom heap allocator is used to reduce these costs.</li> +<li>foundLostPairsCapacity defines the maximum number of found or lost pairs that the GPU broad phase can produce in a single frame. This does not limit the total number of pairs but only limits the number of new or lost pairs that can be detected in a single frame. If more pairs are detected or lost in a frame, an error is emitted and pairs will be dropped by the broad phase.</li> +</ul> +</div> +<div class="section" id="performance-considerations"> +<h2>Performance Considerations<a class="headerlink" href="#performance-considerations" title="Permalink to this headline">¶</a></h2> +<p>GPU rigid bodies can provide extremely large performance advantages over CPU rigid bodies in scenes with several thousand active rigid bodies. However, there are some performance considerations to be taken into account.</p> +<p>GPU rigid bodies currently only accelerate contact generation involving convex hulls and boxes (against convex hulls, boxes, triangle meshes and heighfields). If you make heavy use of other shapes, e.g. capsules or spheres, contact generation involving these shapes will only be processed on CPU.</p> +<p>D6 joints will provide best performance when used with GPU rigid bodies. Other joint types will be partially GPU-accelerated but the performance advantages will be less than the performance advantage exhibited by D6 joints.</p> +<p>Convex hulls with more than 64 vertices or with more than 32 vertices per-face will have their contacts processed by the CPU rather than the GPU, so, if possible, keep vertex counts within these limits. Vertex limits can be defined in cooking to ensure that cooked convex hulls do not exceed these limits.</p> +<p>If your application makes heavy use of contact modification, this may limit the number of pairs that have contact generation performed on the GPU.</p> +<p>Modifying the state of actors forces data to be re-synced to the GPU, e.g. transforms for actors must be updated if the application adjusts global pose, velocities must be updated if the application modifies the bodies' velocities etc.. The associated cost of re-syncing data to the GPU is relatively low but it should be taken into consideration.</p> +<p>Features such as joint projection, CCD and triggers are not GPU accelerated and are still processed on the CPU.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">GPU Rigid Bodies</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#using-gpu-rigid-bodies">Using GPU Rigid Bodies</a></li> +<li><a class="reference internal" href="#what-is-gpu-accelerated">What is GPU accelerated?</a></li> +<li><a class="reference internal" href="#tuning">Tuning</a></li> +<li><a class="reference internal" href="#performance-considerations">Performance Considerations</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="OriginShift.html" + title="previous chapter">Scene Origin</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="GeometryQueries.html" + title="next chapter">Geometry Queries</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" /> + <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="GeometryQueries.html" title="Geometry Queries" + >next</a></li> + <li class="right" > + <a href="OriginShift.html" title="Scene Origin" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Geometry.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Geometry.html new file mode 100644 index 00000000..e8b2bd1e --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Geometry.html @@ -0,0 +1,817 @@ +<!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>Geometry — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Rigid Body Overview" href="RigidBodyOverview.html" /> + <link rel="prev" title="Threading" href="Threading.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="RigidBodyOverview.html" title="Rigid Body Overview" + accesskey="N">next</a></li> + <li class="right" > + <a href="Threading.html" title="Threading" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="geometry"> +<span id="id1"></span><h1>Geometry<a class="headerlink" href="#geometry" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This section discusses the PhysX geometry classes. Geometries are used to build shapes for rigid bodies, as collision triggers, and as volumes in PhysX' scene query system. PhysX also provides standalone functions for testing intersection between geometries, raycasting against them, and sweeping one geometry against another.</p> +<p>Geometries are value types, and inherit from a common base class, PxGeometry. Each geometry class defines a volume or surface with a fixed position and orientation. A transform specifies the frame in which the geometry is interpreted. For plane and capsule geometry types PhysX provides helper functions to construct these transforms from common alternative representations.</p> +<p>Geometries fall into two classes:</p> +<ul class="simple"> +<li>primitives (PxBoxGeometry, PxSphereGeometry, PxCapsuleGeometry, PxPlaneGeometry) where the geometry object contains all of the data</li> +<li>meshes or height fields (PxConvexMeshGeometry, PxTriangleMeshGeometry, PxHeightFieldGeometry), where the geometry object contains a pointer to a much larger object (PxConvexMesh, PxTriangleMesh, PxHeightField respectively) You can use these objects with different scales in each PxGeometry type which references them. The larger objects must be created using a <em>cooking</em> process, described for each type below.</li> +</ul> +<p>When passed into and out of the SDK for use as simulation geometry, the geometry is copied into and out of a PxShape class. It can be awkward in this case to retrieve the geometry without knowing its type, so PhysX provides a union-like wrapper class (PxGeometryHolder) that can be used to pass any geometry type by value. Each mesh (or height field) has a reference count that tracks the number of PxShapes whose geometries reference the mesh.</p> +</div> +<div class="section" id="geometry-types"> +<h2>Geometry Types<a class="headerlink" href="#geometry-types" title="Permalink to this headline">¶</a></h2> +<div class="section" id="spheres"> +<h3>Spheres<a class="headerlink" href="#spheres" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypeSphere.png" src="../_images/GeomTypeSphere.png" /> +<p>A PxSphereGeometry is specified by one attribute, its radius, and is centered at the origin.</p> +</div> +<div class="section" id="capsules"> +<h3>Capsules<a class="headerlink" href="#capsules" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypeCapsule.png" src="../_images/GeomTypeCapsule.png" /> +<p>A PxCapsuleGeometry is centered at the origin. It is specified by a radius and a half-height value by which its axis extends along the positive and negative X-axis.</p> +<p>To create a dynamic actor whose geometry is a capsule standing upright, the shape needs a relative transform that rotates it around the Z-axis by a quarter-circle. By doing this, the capsule will extend along the Y-axis of the actor instead of the X-axis. Setting up the shape and actor is otherwise the same as for the sphere:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">aCapsuleActor</span> <span class="o">=</span> <span class="n">thePhysics</span><span class="o">-></span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">position</span><span class="p">));</span> +<span class="n">PxTransform</span> <span class="nf">relativePose</span><span class="p">(</span><span class="n">PxQuat</span><span class="p">(</span><span class="n">PxHalfPi</span><span class="p">,</span> <span class="n">PxVec</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="mi">1</span><span class="p">)));</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">aCapsuleShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">aCapsuleActor</span><span class="p">,</span> + <span class="n">PxCapsuleGeometry</span><span class="p">(</span><span class="n">radius</span><span class="p">,</span> <span class="n">halfHeight</span><span class="p">),</span> <span class="n">aMaterial</span><span class="p">);</span> +<span class="n">aCapsuleShape</span><span class="o">-></span><span class="n">setLocalPose</span><span class="p">(</span><span class="n">relativePose</span><span class="p">);</span> +<span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">updateMassAndInertia</span><span class="p">(</span><span class="o">*</span><span class="n">aCapsuleActor</span><span class="p">,</span> <span class="n">capsuleDensity</span><span class="p">);</span> +<span class="n">aScene</span><span class="o">-></span><span class="n">addActor</span><span class="p">(</span><span class="n">aCapsuleActor</span><span class="p">);</span> +</pre></div> +</div> +<p>The function PxTransformFromSegment() converts from a line segment defining the capsule axis to a transform and halfheight.</p> +</div> +<div class="section" id="boxes"> +<h3>Boxes<a class="headerlink" href="#boxes" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypeBox.png" src="../_images/GeomTypeBox.png" /> +<p>A PxBoxGeometry has three attributes, the three extents halved:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">aBoxShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">aBoxActor</span><span class="p">,</span> + <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="n">a</span><span class="o">/</span><span class="mi">2</span><span class="p">,</span> <span class="n">b</span><span class="o">/</span><span class="mi">2</span><span class="p">,</span> <span class="n">c</span><span class="o">/</span><span class="mi">2</span><span class="p">),</span> <span class="n">aMaterial</span><span class="p">);</span> +</pre></div> +</div> +<p>Where a, b and c are the side lengths of the resulting box.</p> +</div> +<div class="section" id="planes"> +<h3>Planes<a class="headerlink" href="#planes" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypePlane.png" src="../_images/GeomTypePlane.png" /> +<p>Planes divide space into "above" and "below" them. Everything "below" the plane will collide with it.</p> +<p>The Plane lies on the YZ plane with "above" pointing towards positive X. To convert from a plane equation to an equivalent transform, use the function PxTransformFromPlaneEquation(). PxPlaneEquationFromTransform() performs the reverse conversion.</p> +<p>A PxPlaneGeometry has no attributes, since the shape's pose entirely defines the plane's collision volume.</p> +<p>Shapes with a PxPlaneGeometry may only be created for static actors.</p> +</div> +<div class="section" id="convex-meshes"> +<h3>Convex Meshes<a class="headerlink" href="#convex-meshes" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypeConvex.png" src="../_images/GeomTypeConvex.png" /> +<p>A shape is convex if, given any two points within the shape, the shape contains the line between them. A PxConvexMesh is a convex polyhedron represented as a set of vertices and polygonal faces. The number of vertices and faces of a convex mesh in PhysX is limited to 255.</p> +<p>Creating a PxConvexMesh requires cooking. It is assumed here that the cooking library has already been initialized (see <a class="reference internal" href="Startup.html#startup"><em>Startup and Shutdown</em></a>.) The following steps explain how to create a simple square pyramid.</p> +<p>First, define the vertices of the convex object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="k">const</span> <span class="n">PxVec3</span> <span class="n">convexVerts</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span><span class="n">PxVec3</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span><span class="n">PxVec3</span><span class="p">(</span><span class="mi">1</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="n">PxVec3</span><span class="p">(</span><span class="o">-</span><span class="mi">1</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="n">PxVec3</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="mi">1</span><span class="p">),</span> + <span class="n">PxVec3</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="o">-</span><span class="mi">1</span><span class="p">)};</span> +</pre></div> +</div> +<p>Then construct a description of the convex data layout:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxConvexMeshDesc</span> <span class="n">convexDesc</span><span class="p">;</span> +<span class="n">convexDesc</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="mi">5</span><span class="p">;</span> +<span class="n">convexDesc</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">PxVec3</span><span class="p">);</span> +<span class="n">convexDesc</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">convexVerts</span><span class="p">;</span> +<span class="n">convexDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">=</span> <span class="n">PxConvexFlag</span><span class="o">::</span><span class="n">eCOMPUTE_CONVEX</span><span class="p">;</span> +</pre></div> +</div> +<p>Now use the cooking library to construct a PxConvexMesh:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxDefaultMemoryOutputStream</span> <span class="n">buf</span><span class="p">;</span> +<span class="n">PxConvexMeshCookingResult</span><span class="o">::</span><span class="n">Enum</span> <span class="n">result</span><span class="p">;</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">cooking</span><span class="p">.</span><span class="n">cookConvexMesh</span><span class="p">(</span><span class="n">convexDesc</span><span class="p">,</span> <span class="n">buf</span><span class="p">,</span> <span class="o">&</span><span class="n">result</span><span class="p">))</span> + <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> +<span class="n">PxDefaultMemoryInputData</span> <span class="nf">input</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">getData</span><span class="p">(),</span> <span class="n">buf</span><span class="p">.</span><span class="n">getSize</span><span class="p">());</span> +<span class="n">PxConvexMesh</span><span class="o">*</span> <span class="n">convexMesh</span> <span class="o">=</span> <span class="n">physics</span><span class="o">-></span><span class="n">createConvexMesh</span><span class="p">(</span><span class="n">input</span><span class="p">);</span> +</pre></div> +</div> +<p>Finally, create a shape using a PxConvexMeshGeometry which instances the mesh:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">aConvexShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">aConvexActor</span><span class="p">,</span> + <span class="n">PxConvexMeshGeometry</span><span class="p">(</span><span class="n">convexMesh</span><span class="p">),</span> <span class="n">aMaterial</span><span class="p">);</span> +</pre></div> +</div> +<p>Alternatively the PxConvexMesh can be cooked and directly inserted into PxPhysics without stream serialization. This is useful if real-time cooking is required. It is strongly recommended to use offline cooking and streams. Here is an example showing how to improve cooking speed if needed:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxConvexMeshDesc</span> <span class="n">convexDesc</span><span class="p">;</span> +<span class="n">convexDesc</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="mi">5</span><span class="p">;</span> +<span class="n">convexDesc</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">PxVec3</span><span class="p">);</span> +<span class="n">convexDesc</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">convexVerts</span><span class="p">;</span> +<span class="n">convexDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">=</span> <span class="n">PxConvexFlag</span><span class="o">::</span><span class="n">eCOMPUTE_CONVEX</span> <span class="o">|</span> <span class="n">PxConvexFlag</span><span class="o">::</span><span class="n">eDISABLE_MESH_VALIDATION</span> <span class="o">|</span> <span class="n">PxConvexFlag</span><span class="o">::</span><span class="n">eFAST_INERTIA_COMPUTATION</span><span class="p">;</span> + +<span class="cp">#ifdef _DEBUG</span> + <span class="c1">// mesh should be validated before cooking without the mesh cleaning</span> + <span class="kt">bool</span> <span class="n">res</span> <span class="o">=</span> <span class="n">theCooking</span><span class="o">-></span><span class="n">validateConvexMesh</span><span class="p">(</span><span class="n">convexDesc</span><span class="p">);</span> + <span class="n">PX_ASSERT</span><span class="p">(</span><span class="n">res</span><span class="p">);</span> +<span class="cp">#endif</span> + +<span class="n">PxConvexMesh</span><span class="o">*</span> <span class="n">aConvexMesh</span> <span class="o">=</span> <span class="n">theCooking</span><span class="o">-></span><span class="n">createConvexMesh</span><span class="p">(</span><span class="n">convexDesc</span><span class="p">,</span> + <span class="n">thePhysics</span><span class="o">-></span><span class="n">getPhysicsInsertionCallback</span><span class="p">());</span> +</pre></div> +</div> +<p>Please note that mesh validation is required for debug and checked builds, as creating meshes from unvalidated input descriptors may result in undefined behavior. Providing PxConvexFlag::eFAST_INERTIA_COMPUTATION flag the volume integration will use SIMD code path which does faster computation but with lesser precision.</p> +<p>The user can optionally provide a per-instance PxMeshScale in the PxConvexMeshGeometry. The scale defaults to identity. Negative scale is not supported for convex meshes.</p> +<p>PxConvexMeshGeometry also contains flags to tweak some aspects of the convex object. By default the system computes approximate (loose) bounds around convex objects. Using PxConvexMeshGeometryFlag::eTIGHT_BOUNDS enables smaller/tighter bounds, which are more expensive to compute but could result in improved simulation performance when a lot of convex objects are interacting with each other.</p> +</div> +<div class="section" id="convex-mesh-cooking"> +<h3>Convex Mesh cooking<a class="headerlink" href="#convex-mesh-cooking" title="Permalink to this headline">¶</a></h3> +<p>Convex Mesh cooking transforms the mesh data into a form which allows the SDK to perform efficient collision detection. The input to cooking is defined using the input PxConvexMeshDesc.</p> +<p>There are different ways to fill in this structure, depending on whether you want to produce a convex mesh starting from just a cloud of vertices, or whether you have the vertices and faces of a polyhedron already.</p> +<div class="section" id="if-only-vertex-points-are-provided"> +<h4>If Only Vertex Points are Provided<a class="headerlink" href="#if-only-vertex-points-are-provided" title="Permalink to this headline">¶</a></h4> +<p>When providing only vertices, set the PxConvexFlag::eCOMPUTE_CONVEX flag to compute the mesh:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxConvexMeshDesc</span> <span class="n">convexDesc</span><span class="p">;</span> +<span class="n">convexDesc</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="mi">20</span><span class="p">;</span> +<span class="n">convexDesc</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">PxVec3</span><span class="p">);</span> +<span class="n">convexDesc</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">convexVerts</span><span class="p">;</span> +<span class="n">convexDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">=</span> <span class="n">PxConvexFlag</span><span class="o">::</span><span class="n">eCOMPUTE_CONVEX</span><span class="p">;</span> +<span class="n">convexDesc</span><span class="p">.</span><span class="n">maxVerts</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span> + +<span class="n">PxDefaultMemoryOutputStream</span> <span class="n">buf</span><span class="p">;</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">cooking</span><span class="p">.</span><span class="n">cookConvexMesh</span><span class="p">(</span><span class="n">convexDesc</span><span class="p">,</span> <span class="n">buf</span><span class="p">))</span> + <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> +</pre></div> +</div> +<p>The algorithm tries to create a convex mesh from the source vertices. The field convexDesc.vertexLimit specifies the limit for the maximum number of vertices in the resulting hull.</p> +<p>This routine can sometimes fail when the source data is geometrically challenging, for example if it contains a lot of vertices close to each-other. If cooking fails, an error is reported to the error stream and the routine returns false.</p> +<p>If PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES is used, the algorithm does not include triangles with an area less than PxCookingParams::areaTestEpsilon. If the algorithm cannot find 4 initial vertices without a small triangle, PxConvexMeshCookingResult::eZERO_AREA_TEST_FAILED is returned. This means that the provided vertices were in a very small area and the cooker could not produce a valid hull. +The toolkit helper function PxToolkit::createConvexMeshSafe illustrates the most robust strategy for convex mesh cooking. First it tries to create the hull without inflation. If that fails it tries inflation, and if that also fails, uses an AABB or OBB.</p> +<p>It is recommended to provide vertices around origin and put transformation in PxShape.</p> +<p>If huge amount of input vertices are provided, it might be useful to quantize the input vertices, in this case use PxConvexFlag::eQUANTIZE_INPUT and set the required PxConvexMeshDesc::quantizedCount.</p> +<p>Convex cooking supports two different algorithms:</p> +<div class="section" id="quickhull-algorithm"> +<h5>Quickhull Algorithm<a class="headerlink" href="#quickhull-algorithm" title="Permalink to this headline">¶</a></h5> +<p>This algorithm does not use inflation. It creates a convex mesh whose vertices are a subset of the original vertices, and the number of vertices is guaranteed to be no more than the specified maximum.</p> +<p>The Quickhull algorithm performs these steps:</p> +<ul class="simple"> +<li>Cleans the vertices - removes duplicates etc.</li> +<li>Finds a subset of vertices, no more than vertexLimit, that enclose the input set.</li> +<li>If the vertexLimit is reached, expand the limited hull around the input vertices to ensure we encapsulate all the input vertices.</li> +<li>Compute a vertex map table. (Requires at least 3 neighbor polygons for each vertex.)</li> +<li>Checks the polygon data - verifies that all vertices are on or inside the hull, etc.</li> +<li>Computes mass and inertia tensor assuming density is 1.</li> +<li>Saves data to stream.</li> +</ul> +</div> +<div class="section" id="inflation-based-incremental-algorithm"> +<h5>Inflation Based Incremental Algorithm<a class="headerlink" href="#inflation-based-incremental-algorithm" title="Permalink to this headline">¶</a></h5> +<p>This algorithm always uses the PxConvexFlag::eINFLATE_CONVEX flag and inflates the hull planes by PxCookingParams::skinWidth.</p> +<p>The Inflation Incremental Algorithm performs these steps:</p> +<ul class="simple"> +<li>Cleans the vertices - removes duplicates etc.</li> +<li>Finds a subset of vertices, no more than vertexLimit, that enclose the input set.</li> +<li>Creates planes from the produced enclosed hull.</li> +<li>Inflates planes by defined PxCookingParams::skinWidth.</li> +<li>Crops the AABB by the inflated planes and produces a new hull.</li> +<li>Computes vertex map table. (Requires at least 3 neighbor polygons for each vertex.)</li> +<li>Checks polygon data - verifies all vertices are on or inside the hull, etc.</li> +<li>Computes mass and inertia tensor assuming density is 1.</li> +<li>Saves data to stream.</li> +</ul> +<p>Note that the inflation based algorithm can produce hulls with more input vertices. The algorithm is significantly slower than the quickhull and produces significantly less stable results. It is recommended to use the quickhull algorithm.</p> +</div> +<div class="section" id="vertex-limit-algorithms"> +<h5>Vertex Limit Algorithms<a class="headerlink" href="#vertex-limit-algorithms" title="Permalink to this headline">¶</a></h5> +<p>If a vertex limit has been provided, there are two algorithms that handle vertex limitation.</p> +<p>The default algorithm computes the full hull, and an OBB around the input vertices. This OBB is then sliced with the hull planes until the vertex limit is reached. The default algorithm requires the vertex limit to be set to at least 8, and typically produces results that are much better quality than are produced by plane shifting.</p> +<p>When plane shifting is enabled (PxConvexFlag::ePLANE_SHIFTING), the hull computation stops when vertex limit is reached. The hull planes are then shifted to contain all input vertices, and the new plane intersection points are then used to generate the final hull with the given vertex limit. Plane shifting may produce sharp edges to vertices very far away from the input cloud, and does not guarantee that all input vertices are inside the resulting hull. However, it can be used with a vertex limit as low as 4, and so may be a better choice for cases such as small pieces of debris with very low vertex counts.</p> +</div> +</div> +<div class="section" id="vertex-points-indices-and-polygons-are-provided"> +<h4>Vertex Points, Indices and Polygons are Provided<a class="headerlink" href="#vertex-points-indices-and-polygons-are-provided" title="Permalink to this headline">¶</a></h4> +<p>To create a PxConvexMesh given a set of input vertices (convexVerts) and polygons (hullPolygons):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxConvexMeshDesc</span> <span class="n">convexDesc</span><span class="p">;</span> +<span class="n">convexDesc</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="mi">12</span><span class="p">;</span> +<span class="n">convexDesc</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">PxVec3</span><span class="p">);</span> +<span class="n">convexDesc</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">convexVerts</span><span class="p">;</span> +<span class="n">convexDescPolygons</span><span class="p">.</span><span class="n">polygons</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="mi">20</span><span class="p">;</span> +<span class="n">convexDescPolygons</span><span class="p">.</span><span class="n">polygons</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">PxHullPolygon</span><span class="p">);</span> +<span class="n">convexDescPolygons</span><span class="p">.</span><span class="n">polygons</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">hullPolygons</span><span class="p">;</span> +<span class="n">convexDesc</span><span class="p">.</span><span class="n">flags</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + +<span class="n">PxDefaultMemoryOutputStream</span> <span class="n">buf</span><span class="p">;</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">cooking</span><span class="p">.</span><span class="n">cookConvexMesh</span><span class="p">(</span><span class="n">convexDesc</span><span class="p">,</span> <span class="n">buf</span><span class="p">))</span> + <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> +</pre></div> +</div> +<p>When points and polygons are provided, the SDK validates the mesh and creates the PxConvexmesh directly. This is the fastest way to create a convex mesh. Note that the SDK requires at least 3 neighbor polygons for each vertex. Otherwise acceleration structure for PCM is not created and it does result in performance penalty if PCM is enabled.</p> +<p>(NOTE: the SDK should reject such a mesh as invalid)</p> +<p>Internal steps during convex cooking:</p> +<ul class="simple"> +<li>Compute vertex map table, requires at least 3 neighbor polygons for each vertex.</li> +<li>Check polygons data - check if all vertices are on or inside the hull, etc.</li> +<li>Compute mass and inertia tensor assuming density 1.</li> +<li>Save data to stream.</li> +</ul> +</div> +</div> +<div class="section" id="triangle-meshes"> +<h3>Triangle Meshes<a class="headerlink" href="#triangle-meshes" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypeMesh.png" src="../_images/GeomTypeMesh.png" /> +<p>Like graphical triangle meshes, a collision triangle mesh consists of a collection of vertices and the triangle indices. Triangle mesh creation requires use of the cooking library. It is assumed here that the cooking library has already been initialized (see <a class="reference internal" href="Startup.html#startup"><em>Startup and Shutdown</em></a>.):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxTriangleMeshDesc</span> <span class="n">meshDesc</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">nbVerts</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">PxVec3</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">verts</span><span class="p">;</span> + +<span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="n">triCount</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">stride</span> <span class="o">=</span> <span class="mi">3</span><span class="o">*</span><span class="k">sizeof</span><span class="p">(</span><span class="n">PxU32</span><span class="p">);</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">indices32</span><span class="p">;</span> + +<span class="n">PxDefaultMemoryOutputStream</span> <span class="n">writeBuffer</span><span class="p">;</span> +<span class="n">PxTriangleMeshCookingResult</span><span class="o">::</span><span class="n">Enum</span> <span class="n">result</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">cooking</span><span class="p">.</span><span class="n">cookTriangleMesh</span><span class="p">(</span><span class="n">meshDesc</span><span class="p">,</span> <span class="n">writeBuffer</span><span class="p">,</span><span class="n">result</span><span class="p">);</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">status</span><span class="p">)</span> + <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> + +<span class="n">PxDefaultMemoryInputData</span> <span class="nf">readBuffer</span><span class="p">(</span><span class="n">writeBuffer</span><span class="p">.</span><span class="n">getData</span><span class="p">(),</span> <span class="n">writeBuffer</span><span class="p">.</span><span class="n">getSize</span><span class="p">());</span> +<span class="k">return</span> <span class="n">physics</span><span class="p">.</span><span class="n">createTriangleMesh</span><span class="p">(</span><span class="n">readBuffer</span><span class="p">);</span> +</pre></div> +</div> +<p>Alternatively <em>PxTriangleMesh</em> can be cooked and directly inserted into <em>PxPhysics</em> without stream serialization. This is useful if real-time cooking is required. It is strongly recommended to use offline cooking and streams. Example how to improve cooking speed if needed:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxTolerancesScale</span> <span class="n">scale</span><span class="p">;</span> +<span class="n">PxCookingParams</span> <span class="nf">params</span><span class="p">(</span><span class="n">scale</span><span class="p">);</span> +<span class="c1">// disable mesh cleaning - perform mesh validation on development configurations</span> +<span class="n">params</span><span class="p">.</span><span class="n">meshPreprocessParams</span> <span class="o">|=</span> <span class="n">PxMeshPreprocessingFlag</span><span class="o">::</span><span class="n">eDISABLE_CLEAN_MESH</span><span class="p">;</span> +<span class="c1">// disable edge precompute, edges are set for each triangle, slows contact generation</span> +<span class="n">params</span><span class="p">.</span><span class="n">meshPreprocessParams</span> <span class="o">|=</span> <span class="n">PxMeshPreprocessingFlag</span><span class="o">::</span><span class="n">eDISABLE_ACTIVE_EDGES_PRECOMPUTE</span><span class="p">;</span> +<span class="c1">// lower hierarchy for internal mesh</span> +<span class="n">params</span><span class="p">.</span><span class="n">meshCookingHint</span> <span class="o">=</span> <span class="n">PxMeshCookingHint</span><span class="o">::</span><span class="n">eCOOKING_PERFORMANCE</span><span class="p">;</span> + +<span class="n">theCooking</span><span class="o">-></span><span class="n">setParams</span><span class="p">(</span><span class="n">params</span><span class="p">);</span> + +<span class="n">PxTriangleMeshDesc</span> <span class="n">meshDesc</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">nbVerts</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">PxVec3</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">verts</span><span class="p">;</span> + +<span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">count</span> <span class="o">=</span> <span class="n">triCount</span><span class="p">;</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">stride</span> <span class="o">=</span> <span class="mi">3</span><span class="o">*</span><span class="k">sizeof</span><span class="p">(</span><span class="n">PxU32</span><span class="p">);</span> +<span class="n">meshDesc</span><span class="p">.</span><span class="n">triangles</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">indices32</span><span class="p">;</span> + +<span class="cp">#ifdef _DEBUG</span> + <span class="c1">// mesh should be validated before cooked without the mesh cleaning</span> + <span class="kt">bool</span> <span class="n">res</span> <span class="o">=</span> <span class="n">theCooking</span><span class="o">-></span><span class="n">validateTriangleMesh</span><span class="p">(</span><span class="n">meshDesc</span><span class="p">);</span> + <span class="n">PX_ASSERT</span><span class="p">(</span><span class="n">res</span><span class="p">);</span> +<span class="cp">#endif</span> + +<span class="n">PxTriangleMesh</span><span class="o">*</span> <span class="n">aTriangleMesh</span> <span class="o">=</span> <span class="n">theCooking</span><span class="o">-></span><span class="n">createTriangleMesh</span><span class="p">(</span><span class="n">meshDesc</span><span class="p">,</span> + <span class="n">thePhysics</span><span class="o">-></span><span class="n">getPhysicsInsertionCallback</span><span class="p">());</span> +</pre></div> +</div> +<p>Indices can be 16 or 32 bit. The strides used here assume that vertices and indices are arrays of PxVec3s and 32bit integers respectively with no gaps in the data layout.</p> +<p>Returned result enum <em>PxTriangleMeshCookingResult::eLARGE_TRIANGLE</em> does warn the user if the mesh contains large triangles, which should be tessellated to ensure better simulation and CCT stability.</p> +<p>Like height fields, triangle meshes support per-triangle material indices. To use per-triangle materials for a mesh, provide per-triangle indices to the cooking library in the mesh descriptor. Later, when creating the PxShape, supply a table mapping the index values in the mesh to material instances.</p> +<div class="section" id="triangle-mesh-cooking"> +<h4>Triangle Mesh cooking<a class="headerlink" href="#triangle-mesh-cooking" title="Permalink to this headline">¶</a></h4> +<p>Triangle mesh cooking proceeds as follows:</p> +<ul class="simple"> +<li>Check validity of input vertices.</li> +<li>Weld vertices and check triangle sizes.</li> +<li>create acceleration structure for queries.</li> +<li>Compute edge convexity information and adjacencies.</li> +<li>Save data to stream.</li> +</ul> +<p>Note that mesh cleaning may result in the set of triangles produced by cooking being a subset different from the original input set. Mesh cleaning removes invalid triangles (containing out-of-range vertex references), duplicate triangles, and zero-area triangles. When this happens, PhysX optionally outputs a mesh remapping table that links each internal triangle to its source triangle in the user's data.</p> +<p>There are multiple parameters to control mesh creation.</p> +<p>In <em>PxTriangleMeshDesc</em>:</p> +<ul class="simple"> +<li><em>materialIndices</em> defines per triangle materials. When a triangle mesh collides with another object, a material is required at the collision point. If materialIndices is NULL, then the material of the PxShape instance is used.</li> +</ul> +<p>In <em>PxCookingParams</em>:</p> +<ul> +<li><p class="first"><em>scale</em> defines Tolerance scale is used to check if cooked triangles are not too huge. This check will help with simulation stability.</p> +</li> +<li><p class="first"><em>suppressTriangleMeshRemapTable</em> specifies whether the face remap table is created. If not, this saves a significant amount of memory, but the SDK will not be able to provide information about which original mesh triangle is hit in collisions, sweeps or raycasts hits.</p> +</li> +<li><p class="first"><em>buildTriangleAdjacencies</em> specifies if the triangle adjacency information is created. The adjacent triangles can be retrieved for a given triangle using the getTriangle.</p> +</li> +<li><dl class="first docutils"> +<dt><em>meshPreprocessParams</em> specifies mesh pre-processing parameters.</dt> +<dd><ul class="first last simple"> +<li><em>PxMeshPreprocessingFlag::eWELD_VERTICES</em> enables vertex welding during triangle mesh cooking.</li> +<li><em>PxMeshPreprocessingFlag::eDISABLE_CLEAN_MESH</em> disables mesh clean process. Vertices duplicities are not searched, huge triangles test is not done. Vertices welding is not done. Does speed up the cooking.</li> +<li><em>PxMeshPreprocessingFlag::eDISABLE_ACTIVE_EDGES_PRECOMPUTE</em> disables vertex edge precomputation. Makes cooking faster but slow up contact generation.</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first"><em>meshWeldTolerance</em> - If mesh welding is enabled, this controls the distance at which vertices are welded. If mesh welding is not enabled, this value defines the acceptance distance for mesh validation. Provided no two vertices are within this distance, the mesh is considered to be clean. If not, a warning will be emitted. Having a clean mesh is required to achieve the best possible performance.</p> +</li> +<li><dl class="first docutils"> +<dt><em>midphaseDesc</em> specifies the desired midphase acceleration structure descriptor.</dt> +<dd><ul class="first last simple"> +<li><em>PxBVH33MidphaseDesc - PxMeshMidPhase::eBVH33</em> is the default structure. It was the one used in recent PhysX versions up to PhysX 3.3. It has great performance and is supported on all platforms.</li> +<li><em>PxBVH34MidphaseDesc - PxMeshMidPhase::eBVH34</em> is a revisited implementation introduced in PhysX 3.4. It can be significantly faster both in terms of cooking performance and runtime performance, but it is currently only available on platforms supporting the SSE2 instuction set.</li> +</ul> +</dd> +</dl> +</li> +</ul> +<p><em>PxBVH33MidphaseDesc params</em>:</p> +<ul class="simple"> +<li><em>meshCookingHint</em> specifies mesh hierarchy construction preferences. Enables better cooking performance over collision performance, for applications where cooking performance is more important than best quality mesh creation.</li> +<li><em>meshSizePerformanceTradeOff</em> specifies the trade-off between mesh size and runtime performance.</li> +</ul> +<p><em>PxBVH34MidphaseDesc params</em>:</p> +<ul class="simple"> +<li><em>numTrisPerLeaf</em> specifies the number of triangles per leaf. Less triangles per leaf produces larger meshes with general better runtime performance and worse cooking performance.</li> +</ul> +</div> +</div> +<div class="section" id="height-fields"> +<h3>Height Fields<a class="headerlink" href="#height-fields" title="Permalink to this headline">¶</a></h3> +<img alt="../_images/GeomTypeHeightField.png" src="../_images/GeomTypeHeightField.png" /> +<dl class="docutils"> +<dt>Local space axes for the height fields are:</dt> +<dd><ul class="first last simple"> +<li>Row - X axis</li> +<li>Column - Z axis</li> +<li>Height - Y axis</li> +</ul> +</dd> +</dl> +<p>As the name suggests, terrains can be described by just the height values on a regular, rectangular sampling grid:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxHeightFieldSample</span><span class="o">*</span> <span class="n">samples</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxHeightFieldSample</span><span class="o">*</span><span class="p">)</span><span class="n">alloc</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">PxHeightFieldSample</span><span class="p">)</span><span class="o">*</span> + <span class="p">(</span><span class="n">numRows</span><span class="o">*</span><span class="n">numCols</span><span class="p">));</span> +</pre></div> +</div> +<p>Each sample consists of a 16 bit integer height value, two materials (for the two triangles in the samples rectangle) and a tessellation flag.</p> +<p>The flag and materials refer to the cell below and to the right of the sample point, and indicate along which diagonal to split it into triangles, and the materials of those triangles. A special predefined material <tt class="docutils literal"><span class="pre">PxHeightFieldMaterial::eHOLE</span></tt> specifies a hole in the height field. See the reference documentation for <em>PxHeightFieldSample</em> for more details.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="50%" /> +<col width="50%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head">Tesselation flag set</th> +<th class="head">Tesselation flag not set</th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><img alt="../_images/heightfieldTriMat1.png" class="first last" src="../_images/heightfieldTriMat1.png" /> +</td> +<td><img alt="../_images/heightfieldTriMat2.png" class="first last" src="../_images/heightfieldTriMat2.png" /> +</td> +</tr> +</tbody> +</table> +<p>Examples:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="31%" /> +<col width="69%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head">Tesselation flags</th> +<th class="head">Result</th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><div class="first last line-block"> +<div class="line">0,0,0</div> +<div class="line">0,0,0</div> +<div class="line">0,0,0</div> +</div> +</td> +<td><img alt="../_images/heightfieldTess1.png" class="first last" src="../_images/heightfieldTess1.png" /> +</td> +</tr> +<tr class="row-odd"><td><div class="first last line-block"> +<div class="line">1,1,1</div> +<div class="line">1,1,1</div> +<div class="line">1,1,1</div> +</div> +</td> +<td><img alt="../_images/heightfieldTess2.png" class="first last" src="../_images/heightfieldTess2.png" /> +</td> +</tr> +<tr class="row-even"><td><div class="first last line-block"> +<div class="line">0,1,0</div> +<div class="line">1,0,1</div> +<div class="line">0,1,0</div> +</div> +</td> +<td><img alt="../_images/heightfieldTess3.png" class="first last" src="../_images/heightfieldTess3.png" /> +</td> +</tr> +</tbody> +</table> +<p>To tell the system the number of sampled heights in each direction, use a descriptor to instantiate a PxHeightField object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxHeightFieldDesc</span> <span class="n">hfDesc</span><span class="p">;</span> +<span class="n">hfDesc</span><span class="p">.</span><span class="n">format</span> <span class="o">=</span> <span class="n">PxHeightFieldFormat</span><span class="o">::</span><span class="n">eS16_TM</span><span class="p">;</span> +<span class="n">hfDesc</span><span class="p">.</span><span class="n">nbColumns</span> <span class="o">=</span> <span class="n">numCols</span><span class="p">;</span> +<span class="n">hfDesc</span><span class="p">.</span><span class="n">nbRows</span> <span class="o">=</span> <span class="n">numRows</span><span class="p">;</span> +<span class="n">hfDesc</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">samples</span><span class="p">;</span> +<span class="n">hfDesc</span><span class="p">.</span><span class="n">samples</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">PxHeightFieldSample</span><span class="p">);</span> + +<span class="n">PxHeightField</span><span class="o">*</span> <span class="n">aHeightField</span> <span class="o">=</span> <span class="n">theCooking</span><span class="o">-></span><span class="n">createHeightField</span><span class="p">(</span><span class="n">hfDesc</span><span class="p">,</span> + <span class="n">thePhysics</span><span class="o">-></span><span class="n">getPhysicsInsertionCallback</span><span class="p">());</span> +</pre></div> +</div> +<p>Now create a PxHeightFieldGeometry and a shape:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxHeightFieldGeometry</span> <span class="nf">hfGeom</span><span class="p">(</span><span class="n">aHeightField</span><span class="p">,</span> <span class="n">PxMeshGeometryFlags</span><span class="p">(),</span> <span class="n">heightScale</span><span class="p">,</span> <span class="n">rowScale</span><span class="p">,</span> + <span class="n">colScale</span><span class="p">);</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">aHeightFieldShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">aHeightFieldActor</span><span class="p">,</span> + <span class="n">hfGeom</span><span class="p">,</span> <span class="n">aMaterialArray</span><span class="p">,</span> <span class="n">nbMaterials</span><span class="p">);</span> +</pre></div> +</div> +<p>The row and column scales tell the system how far apart the sampled points lie in the associated direction. The height scale scales the integer height values to a floating point range.</p> +<p>The variant of <em>createExclusiveShape()</em> used here specifies an array of materials for the height field, which will be indexed by the material indices of each cell to resolve collisions with that cell. The single-material variant may be used instead, but the height field material indices must all be a single value or the special value <tt class="docutils literal"><span class="pre">eHOLE</span></tt>.</p> +<p>Contact generation with triangle edges at the terrain's borders can be disabled using the <em>PxHeightFieldFlag::eNO_BOUNDARY_EDGES</em> flag, allowing more efficient contact generation when there are multiple heightfield shapes arranged so that their edges touch.</p> +<div class="section" id="heightfield-cooking"> +<h4>Heightfield cooking<a class="headerlink" href="#heightfield-cooking" title="Permalink to this headline">¶</a></h4> +<p>Heightfield data can be cooked in offline and then used to createHeightField. The cooking does precompute and store the edge information. This allows much faster create of the heightfield, since the edges are already precomputed. It is very useful if you need to create heightfields in the runtime, since it does improve the speed of createHeightField significantly.</p> +<p>Heightfield cooking proceeds as follows:</p> +<ul class="simple"> +<li>Load heightfield samples into internal memory.</li> +<li>Precompute edge collision information.</li> +<li>Save data to stream.</li> +</ul> +</div> +<div class="section" id="unified-heightfields"> +<h4>Unified Heightfields<a class="headerlink" href="#unified-heightfields" title="Permalink to this headline">¶</a></h4> +<p>PhysX provides two contact generation approaches for heightfields. These are:</p> +<ul class="simple"> +<li>Default unified heightfield contact generation.</li> +<li>Legacy heightfield contact generation.</li> +</ul> +<p>The default unified heightfield contact generation approach extracts triangles from the heightfield and utilizes the same low-level contact generation code that is used for contact generation against triangle meshes. This approach ensures equivalent behavior and performance if triangle meshes or heightfields are used interchangeably. However, with this approach, the heightfield surface has no thickness so fast-moving objects may tunnel if CCD is not enabled.</p> +<p>The legacy heightfield collision code, which was default in previous versions of PhysX, works differently from triangle mesh contact generation. In addition to generating contacts with shapes touching the surface of the heightfield, it generates contacts with shapes that are beneath the surface. The heightfield's "thickness" is used to control how far beneath the surface contacts are generated. This works by extruding the AABB of the heightfield in the broad phase by the "thickness" along the vertical axis. Contacts are generated for any shape below the surface whose bounds intersects the heightfields extruded bounds.</p> +<p>Unified heightfield contact generation is enabled by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRegisterHeightFields</span><span class="p">(</span><span class="n">PxPhysics</span><span class="o">&</span> <span class="n">physics</span><span class="p">);</span> +</pre></div> +</div> +<p>Legacy heightfield contact generation is enabled by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRegisterLegacyHeightFields</span><span class="p">(</span><span class="n">PxPhysics</span><span class="o">&</span> <span class="n">physics</span><span class="p">);</span> +</pre></div> +</div> +<p>These calls must be made before and scenes have been created, otherwise warnings will be issued. The heightfield collision setting is a global setting, and it applies to all scenes.</p> +<p>If PxCreatePhysics(...) is called, this will automatically call PxRegisterHeightFields(...) to register the default, unified heightfield collision approach. If PxCreateBasePhysics(...) is called, no heightfield contact generation is registered by default. If heightfields are used, the application must call the appropriate heightfield registration function.</p> +</div> +</div> +</div> +<div class="section" id="mesh-scaling"> +<h2>Mesh Scaling<a class="headerlink" href="#mesh-scaling" title="Permalink to this headline">¶</a></h2> +<p>A shared PxTriangleMesh or PxConvexMesh may be stretched or compressed when it is instanced by a geometry. This allows multiple instancing of the same mesh with different scale factors applied. Scaling is specified with the PxMeshScale class, which defines scale factors to be applied along 3 orthogonal axes. A factor greater than 1.0 results in stretching, while a factor less than 1.0 results in compression. The directions of the axes are governed by a quaternion, and specified in the local frame of the shape.</p> +<p>Negative mesh scale is supported, with negative values producing a reflection along each corresponding axis. In addition PhysX will flip the normals for mesh triangles when scale.x*scale.y*scale.z < 0.</p> +<p>The following code creates a shape with a PxTriangleMesh scaled by a factor of x along the x-axis, y along the y-axis, and z along the z-axis:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// created earlier</span> +<span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">myActor</span><span class="p">;</span> +<span class="n">PxTriangleMesh</span><span class="o">*</span> <span class="n">myTriMesh</span><span class="p">;</span> +<span class="n">PxMaterial</span><span class="o">*</span> <span class="n">myMaterial</span><span class="p">;</span> + +<span class="c1">// create a shape instancing a triangle mesh at the given scale</span> +<span class="n">PxMeshScale</span> <span class="nf">scale</span><span class="p">(</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">PxQuat</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> +<span class="n">PxTriangleMeshGeometry</span> <span class="nf">geom</span><span class="p">(</span><span class="n">myTriMesh</span><span class="p">,</span><span class="n">scale</span><span class="p">);</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">myTriMeshShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">myActor</span><span class="p">,</span><span class="n">geom</span><span class="p">,</span><span class="o">*</span><span class="n">myMaterial</span><span class="p">);</span> +</pre></div> +</div> +<p>Convex meshes are scaled using the PxMeshScale class in a similar manner. The following code creates a shape with a PxConvexMesh scaled by a factor of x along (sqrt(1/2), 1.0, -sqrt(1/2)), by a factor of y along (0,1,0) and a by a factor of z along (sqrt(1/2), 1.0, sqrt(1/2)):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxMeshScale</span> <span class="nf">scale</span><span class="p">(</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">PxQuat</span> <span class="n">quat</span><span class="p">(</span><span class="n">PxPi</span><span class="o">*</span><span class="mf">0.25f</span><span class="p">,</span> <span class="n">PxVec3</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">)));</span> +<span class="n">PxConvexMeshGeometry</span> <span class="nf">geom</span><span class="p">(</span><span class="n">myTriMesh</span><span class="p">,</span><span class="n">scale</span><span class="p">);</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">myConvexMeshShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">myActor</span><span class="p">,</span><span class="n">geom</span><span class="p">,</span><span class="o">*</span><span class="n">myMaterial</span><span class="p">);</span> +</pre></div> +</div> +<p>Height fields can also be scaled, using scale factors stored in PxHeightFieldGeometry. In this case the scale is assumed to be along the axes of the rows, columns and height directions of the height field. The scaling of is demonstrated in SampleNorthPole in SampleNorthPoleBuilder.cpp:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxHeightFieldGeometry</span> <span class="nf">hfGeom</span><span class="p">(</span><span class="n">heightField</span><span class="p">,</span> <span class="n">PxMeshGeometryFlags</span><span class="p">(),</span> <span class="n">heightScale</span><span class="p">,</span> <span class="n">hfScale</span><span class="p">,</span> <span class="n">hfScale</span><span class="p">);</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">hfShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">hfActor</span><span class="p">,</span> <span class="n">hfGeom</span><span class="p">,</span> <span class="n">getDefaultMaterial</span><span class="p">());</span> +</pre></div> +</div> +<p>In this example, the coordinates along the x and z axes are scaled by hfScale, while the sample heights are scaled by heightScale.</p> +</div> +<div class="section" id="pxgeometryholder"> +<h2>PxGeometryHolder<a class="headerlink" href="#pxgeometryholder" title="Permalink to this headline">¶</a></h2> +<p>When a geometry is provided for a shape, either on creation or with <em>PxShape::setGeometry()</em>, the geometry is copied into the SDK's internal structures. If you know the type of a shape's geometry you may retrieve it directly:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxBoxGeometry</span> <span class="n">boxGeom</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">shape</span><span class="o">-></span><span class="n">getBoxGeometry</span><span class="p">(</span><span class="n">geometry</span><span class="p">);</span> +</pre></div> +</div> +<p>The status return code is set to false if the shape's geometry is not of the expected type.</p> +<p>However, it is often convenient to retrieve a geometry object from a shape without first knowing its type - for example, to call a function which takes a PxGeometry reference as an argument.</p> +<p>PxGeometryHolder is a union-like class that allows the return of a PxGeometry object by value, regardless of type. Its use is illustrated in the <em>createRenderObjectFromShape()</em> function in PhysXSample.cpp:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxGeometryHolder</span> <span class="n">geom</span> <span class="o">=</span> <span class="n">shape</span><span class="o">-></span><span class="n">getGeometry</span><span class="p">();</span> + +<span class="k">switch</span><span class="p">(</span><span class="n">geom</span><span class="p">.</span><span class="n">getType</span><span class="p">())</span> +<span class="p">{</span> +<span class="k">case</span> <span class="n">PxGeometryType</span>:<span class="o">:</span><span class="n">eSPHERE</span><span class="o">:</span> + <span class="n">shapeRenderActor</span> <span class="o">=</span> <span class="n">SAMPLE_NEW</span><span class="p">(</span><span class="n">RenderSphereActor</span><span class="p">)(</span><span class="n">renderer</span><span class="p">,</span> <span class="n">geom</span><span class="p">.</span><span class="n">sphere</span><span class="p">().</span><span class="n">radius</span><span class="p">);</span> + <span class="k">break</span><span class="p">;</span> +<span class="k">case</span> <span class="n">PxGeometryType</span>:<span class="o">:</span><span class="n">eCAPSULE</span><span class="o">:</span> + <span class="n">shapeRenderActor</span> <span class="o">=</span> <span class="n">SAMPLE_NEW</span><span class="p">(</span><span class="n">RenderCapsuleActor</span><span class="p">)(</span><span class="n">renderer</span><span class="p">,</span> <span class="n">geom</span><span class="p">.</span><span class="n">capsule</span><span class="p">().</span><span class="n">radius</span><span class="p">,</span> + <span class="n">geom</span><span class="p">.</span><span class="n">capsule</span><span class="p">().</span><span class="n">halfHeight</span><span class="p">);</span> + <span class="k">break</span><span class="p">;</span> +<span class="p">...</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The function <em>PxGeometryHolder::any()</em> returns a reference to a PxGeometry object. For example, to compare two shapes in a scene for overlap:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="nf">testForOverlap</span><span class="p">(</span><span class="k">const</span> <span class="n">PxShape</span><span class="o">&</span> <span class="n">s0</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxShape</span><span class="o">&</span> <span class="n">s1</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">return</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">overlap</span><span class="p">(</span><span class="n">s0</span><span class="p">.</span><span class="n">getGeometry</span><span class="p">().</span><span class="n">any</span><span class="p">(),</span> <span class="n">PxShapeExt</span><span class="o">::</span><span class="n">getGlobalPose</span><span class="p">(</span><span class="n">s0</span><span class="p">),</span> + <span class="n">s1</span><span class="p">.</span><span class="n">getGeometry</span><span class="p">().</span><span class="n">any</span><span class="p">(),</span> <span class="n">PxShapeExt</span><span class="o">::</span><span class="n">getGlobalPose</span><span class="p">(</span><span class="n">s1</span><span class="p">));</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="vertex-and-face-data"> +<h2>Vertex and Face Data<a class="headerlink" href="#vertex-and-face-data" title="Permalink to this headline">¶</a></h2> +<p>Convex meshes, triangle meshes, and height fields can all be queried for vertex and face data. This is particularly useful, for example, when rendering the mesh of the convex shape. The function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">RenderBaseActor</span><span class="o">*</span> <span class="n">PhysXSample</span><span class="o">::</span><span class="n">createRenderObjectFromShape</span><span class="p">(</span><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">,</span> + <span class="n">RenderMaterial</span><span class="o">*</span> <span class="n">material</span><span class="p">)</span> +</pre></div> +</div> +<p>in PhysXSample.cpp contains a switch statement with a case for each shape type, illustrating the steps required to query the vertices and faces.</p> +<p>It is possible to get information about triangle from a triangle mesh or height field using PxMeshQuery::getTriangle function. You can also retrieve adjacent triangle indices for the given triangle (triangle triangleNeighbour[i] shares the edge vertex[i]-vertex[(i+1)%3] with triangle indexed as 'triangleIndex', where vertex is in the range from 0 to 2). To enable this feature the triangle mesh is cooked with buildTriangleAdjacencies parameter set to true.</p> +<div class="section" id="id2"> +<h3>Convex Meshes<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>A convex mesh contains an array of vertices, an array of faces, and an index buffer which concatenates the vertex indices for each face. To unpack a convex mesh, the first step is to extract the shared convex mesh:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxConvexMesh</span><span class="o">*</span> <span class="n">convexMesh</span> <span class="o">=</span> <span class="n">geom</span><span class="p">.</span><span class="n">convexMesh</span><span class="p">().</span><span class="n">convexMesh</span><span class="p">;</span> +</pre></div> +</div> +<p>Then obtain references to the vertex and index buffers:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="n">nbVerts</span> <span class="o">=</span> <span class="n">convexMesh</span><span class="o">-></span><span class="n">getNbVertices</span><span class="p">();</span> +<span class="k">const</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">convexVerts</span> <span class="o">=</span> <span class="n">convexMesh</span><span class="o">-></span><span class="n">getVertices</span><span class="p">();</span> +<span class="k">const</span> <span class="n">PxU8</span><span class="o">*</span> <span class="n">indexBuffer</span> <span class="o">=</span> <span class="n">convexMesh</span><span class="o">-></span><span class="n">getIndexBuffer</span><span class="p">();</span> +</pre></div> +</div> +<p>Now iterate over the array of faces to triangulate them:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="n">offset</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">nbPolygons</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">PxHullPolygon</span> <span class="n">face</span><span class="p">;</span> + <span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">convexMesh</span><span class="o">-></span><span class="n">getPolygonData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">face</span><span class="p">);</span> + <span class="n">PX_ASSERT</span><span class="p">(</span><span class="n">status</span><span class="p">);</span> + + <span class="k">const</span> <span class="n">PxU8</span><span class="o">*</span> <span class="n">faceIndices</span> <span class="o">=</span> <span class="n">indexBuffer</span> <span class="o">+</span> <span class="n">face</span><span class="p">.</span><span class="n">mIndexBase</span><span class="p">;</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">j</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span><span class="n">j</span><span class="o"><</span><span class="n">face</span><span class="p">.</span><span class="n">mNbVerts</span><span class="p">;</span><span class="n">j</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">vertices</span><span class="p">[</span><span class="n">offset</span><span class="o">+</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">convexVerts</span><span class="p">[</span><span class="n">faceIndices</span><span class="p">[</span><span class="n">j</span><span class="p">]];</span> + <span class="n">normals</span><span class="p">[</span><span class="n">offset</span><span class="o">+</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">PxVec3</span><span class="p">(</span><span class="n">face</span><span class="p">.</span><span class="n">mPlane</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">face</span><span class="p">.</span><span class="n">mPlane</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">face</span><span class="p">.</span><span class="n">mPlane</span><span class="p">[</span><span class="mi">2</span><span class="p">]);</span> + <span class="p">}</span> + + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">j</span><span class="o">=</span><span class="mi">2</span><span class="p">;</span><span class="n">j</span><span class="o"><</span><span class="n">face</span><span class="p">.</span><span class="n">mNbVerts</span><span class="p">;</span><span class="n">j</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="o">*</span><span class="n">triangles</span><span class="o">++</span> <span class="o">=</span> <span class="n">PxU16</span><span class="p">(</span><span class="n">offset</span><span class="p">);</span> + <span class="o">*</span><span class="n">triangles</span><span class="o">++</span> <span class="o">=</span> <span class="n">PxU16</span><span class="p">(</span><span class="n">offset</span><span class="o">+</span><span class="n">j</span><span class="p">);</span> + <span class="o">*</span><span class="n">triangles</span><span class="o">++</span> <span class="o">=</span> <span class="n">PxU16</span><span class="p">(</span><span class="n">offset</span><span class="o">+</span><span class="n">j</span><span class="o">-</span><span class="mi">1</span><span class="p">);</span> + <span class="p">}</span> + + <span class="n">offset</span> <span class="o">+=</span> <span class="n">face</span><span class="p">.</span><span class="n">mNbVerts</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Observe that the vertex indices of the polygon begin at indexBuffer[face.mIndexBase], and the count of vertices is given by face.mNbVerts.</p> +</div> +<div class="section" id="id3"> +<h3>Triangle Meshes<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3> +<p>Triangle meshes contain arrays of vertices and index triplets which define the triangles by indexing into the vertex buffer. The arrays can be accessed directly from the shared triangle mesh:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxTriangleMesh</span><span class="o">*</span> <span class="n">tm</span> <span class="o">=</span> <span class="n">geom</span><span class="p">.</span><span class="n">triangleMesh</span><span class="p">().</span><span class="n">triangleMesh</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbVerts</span> <span class="o">=</span> <span class="n">tm</span><span class="o">-></span><span class="n">getNbVertices</span><span class="p">();</span> +<span class="k">const</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">verts</span> <span class="o">=</span> <span class="n">tm</span><span class="o">-></span><span class="n">getVertices</span><span class="p">();</span> +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbTris</span> <span class="o">=</span> <span class="n">tm</span><span class="o">-></span><span class="n">getNbTriangles</span><span class="p">();</span> +<span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">tris</span> <span class="o">=</span> <span class="n">tm</span><span class="o">-></span><span class="n">getTriangles</span><span class="p">();</span> +</pre></div> +</div> +<p>The indices may be stored with either 16-bit or 32-bit values, specified when the mesh was originally cooked. To determine the storage format at runtime, use the API call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="kt">bool</span> <span class="n">has16bitIndices</span> <span class="o">=</span> <span class="n">tm</span><span class="o">-></span><span class="n">has16BitTriangleIndices</span><span class="p">();</span> +</pre></div> +</div> +<p>Assuming that the triangle indices are stored in 16-bit format, find the jth vertex of the ith triangle by:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxU16</span><span class="o">*</span> <span class="n">triIndices</span> <span class="o">=</span> <span class="p">(</span><span class="k">const</span> <span class="n">PxU16</span><span class="o">*</span><span class="p">)</span><span class="n">tris</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxU16</span> <span class="n">index</span> <span class="o">=</span> <span class="n">triIndices</span><span class="p">[</span><span class="mi">3</span><span class="o">*</span><span class="n">i</span> <span class="o">+</span><span class="n">j</span><span class="p">];</span> +</pre></div> +</div> +<p>The corresponding vertex is:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">vertex</span> <span class="o">=</span> <span class="n">verts</span><span class="p">[</span><span class="n">index</span><span class="p">];</span> +</pre></div> +</div> +</div> +<div class="section" id="id4"> +<h3>Height Fields<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3> +<p>The storage of height field data is platform-dependent, and therefore direct access to the height field samples is not provided. Instead, calls are provided to render the samples to a user-supplied buffer.</p> +<p>Again, the first step is to retrieve the geometry for the height field:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxHeightFieldGeometry</span><span class="o">&</span> <span class="n">geometry</span> <span class="o">=</span> <span class="n">geom</span><span class="p">.</span><span class="n">heightField</span><span class="p">();</span> +</pre></div> +</div> +<p>The height field has three scaling parameters:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxReal</span> <span class="n">rs</span> <span class="o">=</span> <span class="n">geometry</span><span class="p">.</span><span class="n">rowScale</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxReal</span> <span class="n">hs</span> <span class="o">=</span> <span class="n">geometry</span><span class="p">.</span><span class="n">heightScale</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxReal</span> <span class="n">cs</span> <span class="o">=</span> <span class="n">geometry</span><span class="p">.</span><span class="n">columnScale</span><span class="p">;</span> +</pre></div> +</div> +<p>And a shared data structure, which stores the row and column count:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxHeightField</span><span class="o">*</span> <span class="n">hf</span> <span class="o">=</span> <span class="n">geometry</span><span class="p">.</span><span class="n">heightField</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbCols</span> <span class="o">=</span> <span class="n">hf</span><span class="o">-></span><span class="n">getNbColumns</span><span class="p">();</span> +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbRows</span> <span class="o">=</span> <span class="n">hf</span><span class="o">-></span><span class="n">getNbRows</span><span class="p">();</span> +</pre></div> +</div> +<p>To render the height field, first extract the samples to an array:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbVerts</span> <span class="o">=</span> <span class="n">nbRows</span> <span class="o">*</span> <span class="n">nbCols</span><span class="p">;</span> +<span class="n">PxHeightFieldSample</span><span class="o">*</span> <span class="n">sampleBuffer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxHeightFieldSample</span><span class="p">[</span><span class="n">nbVerts</span><span class="p">];</span> +<span class="n">hf</span><span class="o">-></span><span class="n">saveCells</span><span class="p">(</span><span class="n">sampleBuffer</span><span class="p">,</span> <span class="n">nbVerts</span> <span class="o">*</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">PxHeightFieldSample</span><span class="p">));</span> +</pre></div> +</div> +<p>The samples are stored in row-major order; that is, row0 is stored first, followed by row1, then row2, and so on. Thus the sample corresponding to the ith row and the jth column is i*nbCols + j.</p> +<p>Evaluate the scaled vertices of the height field as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVec3</span><span class="o">*</span> <span class="n">vertices</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxVec3</span><span class="p">[</span><span class="n">nbVerts</span><span class="p">];</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">nbRows</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">j</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">j</span> <span class="o"><</span> <span class="n">nbCols</span><span class="p">;</span> <span class="n">j</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">vertices</span><span class="p">[</span><span class="n">i</span> <span class="o">*</span> <span class="n">nbCols</span> <span class="o">+</span> <span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">PxVec3</span><span class="p">(</span><span class="n">PxReal</span><span class="p">(</span><span class="n">i</span><span class="p">)</span> <span class="o">*</span> <span class="n">rs</span><span class="p">,</span> <span class="n">PxReal</span><span class="p">(</span><span class="n">sampleBuffer</span><span class="p">[</span><span class="n">j</span> <span class="o">+</span> + <span class="p">(</span><span class="n">i</span><span class="o">*</span><span class="n">nbCols</span><span class="p">)].</span><span class="n">height</span><span class="p">)</span> <span class="o">*</span> <span class="n">hs</span><span class="p">,</span> <span class="n">PxReal</span><span class="p">(</span><span class="n">j</span><span class="p">)</span> <span class="o">*</span> <span class="n">cs</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Then tessellate the field from the samples as required.</p> +</div> +<div class="section" id="heightfield-modification"> +<h3>Heightfield Modification<a class="headerlink" href="#heightfield-modification" title="Permalink to this headline">¶</a></h3> +<p>Heightfield samples can be modified at runtime in rectangular blocks. In the following code snippet we create a HF and modify it's samples:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// create a 5x5 HF with height 100 and materials 2,3</span> +<span class="n">PxHeightFieldSample</span> <span class="n">samples1</span><span class="p">[</span><span class="mi">25</span><span class="p">];</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">25</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">samples1</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">height</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> + <span class="n">samples1</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">materialIndex0</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span> + <span class="n">samples1</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">materialIndex1</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span> +<span class="p">}</span> + +<span class="n">PxHeightFieldDesc</span> <span class="n">heightFieldDesc</span><span class="p">;</span> +<span class="n">heightFieldDesc</span><span class="p">.</span><span class="n">nbColumns</span> <span class="o">=</span> <span class="mi">5</span><span class="p">;</span> +<span class="n">heightFieldDesc</span><span class="p">.</span><span class="n">nbRows</span> <span class="o">=</span> <span class="mi">5</span><span class="p">;</span> +<span class="n">heightFieldDesc</span><span class="p">.</span><span class="n">thickness</span> <span class="o">=</span> <span class="o">-</span><span class="mi">10</span><span class="p">;</span> +<span class="n">heightFieldDesc</span><span class="p">.</span><span class="n">convexEdgeThreshold</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span> +<span class="n">heightFieldDesc</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">samples1</span><span class="p">;</span> +<span class="n">heightFieldDesc</span><span class="p">.</span><span class="n">samples</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">PxHeightFieldSample</span><span class="p">);</span> + +<span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span> <span class="o">=</span> <span class="n">getPhysics</span><span class="p">();</span> +<span class="n">PxHeightField</span><span class="o">*</span> <span class="n">pHeightField</span> <span class="o">=</span> <span class="n">cooking</span><span class="o">-></span><span class="n">createHeightField</span><span class="p">(</span><span class="n">heightFieldDesc</span><span class="p">,</span> <span class="n">physics</span><span class="o">-></span><span class="n">getPhysicsInsertionCallback</span><span class="p">());</span> + +<span class="c1">// create modified HF samples, this 10-sample strip will be used as a modified row</span> +<span class="c1">// Source samples that are out of range of target heightfield will be clipped with no error.</span> +<span class="n">PxHeightFieldSample</span> <span class="n">samplesM</span><span class="p">[</span><span class="mi">10</span><span class="p">];</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">10</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">samplesM</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">height</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">;</span> + <span class="n">samplesM</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">materialIndex0</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> + <span class="n">samplesM</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">materialIndex1</span> <span class="o">=</span> <span class="mi">127</span><span class="p">;</span> +<span class="p">}</span> + +<span class="n">PxHeightFieldDesc</span> <span class="n">desc10Rows</span><span class="p">;</span> +<span class="n">desc10Rows</span><span class="p">.</span><span class="n">nbColumns</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> +<span class="n">desc10Rows</span><span class="p">.</span><span class="n">nbRows</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span> +<span class="n">desc10Rows</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">samplesM</span><span class="p">;</span> +<span class="n">desc10Rows</span><span class="p">.</span><span class="n">samples</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">PxHeightFieldSample</span><span class="p">);</span> + +<span class="n">pHeightField</span><span class="o">-></span><span class="n">modifySamples</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">desc10Rows</span><span class="p">);</span> <span class="c1">// modify row 1 with new sample data</span> +</pre></div> +</div> +<p>PhysX does not keep a mapping from the heightfield to heightfield shapes that reference it. Call PxShape::setGeometry on each shape which references the height field, to ensure that internal data structures are updated to reflect the new geometry:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span> <span class="o">*</span><span class="n">hfShape</span> <span class="o">=</span> <span class="n">userGetHfShape</span><span class="p">();</span> <span class="c1">// the user is responsible for keeping track of</span> + <span class="c1">// shapes associated with modified HF</span> +<span class="n">hfShape</span><span class="o">-></span><span class="n">setGeometry</span><span class="p">(</span><span class="n">PxHeightFieldGeometry</span><span class="p">(</span><span class="n">pHeightField</span><span class="p">,</span> <span class="p">...));</span> +</pre></div> +</div> +<p>Please also note that PxShape::setGeometry() does not guarantee correct/continuous behavior when objects are resting on top of old or new geometry.</p> +<p>The method PxHeightField::getTimestamp() returns the number of times a heightfield has been modified.</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Geometry</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#geometry-types">Geometry Types</a><ul> +<li><a class="reference internal" href="#spheres">Spheres</a></li> +<li><a class="reference internal" href="#capsules">Capsules</a></li> +<li><a class="reference internal" href="#boxes">Boxes</a></li> +<li><a class="reference internal" href="#planes">Planes</a></li> +<li><a class="reference internal" href="#convex-meshes">Convex Meshes</a></li> +<li><a class="reference internal" href="#convex-mesh-cooking">Convex Mesh cooking</a><ul> +<li><a class="reference internal" href="#if-only-vertex-points-are-provided">If Only Vertex Points are Provided</a><ul> +<li><a class="reference internal" href="#quickhull-algorithm">Quickhull Algorithm</a></li> +<li><a class="reference internal" href="#inflation-based-incremental-algorithm">Inflation Based Incremental Algorithm</a></li> +<li><a class="reference internal" href="#vertex-limit-algorithms">Vertex Limit Algorithms</a></li> +</ul> +</li> +<li><a class="reference internal" href="#vertex-points-indices-and-polygons-are-provided">Vertex Points, Indices and Polygons are Provided</a></li> +</ul> +</li> +<li><a class="reference internal" href="#triangle-meshes">Triangle Meshes</a><ul> +<li><a class="reference internal" href="#triangle-mesh-cooking">Triangle Mesh cooking</a></li> +</ul> +</li> +<li><a class="reference internal" href="#height-fields">Height Fields</a><ul> +<li><a class="reference internal" href="#heightfield-cooking">Heightfield cooking</a></li> +<li><a class="reference internal" href="#unified-heightfields">Unified Heightfields</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#mesh-scaling">Mesh Scaling</a></li> +<li><a class="reference internal" href="#pxgeometryholder">PxGeometryHolder</a></li> +<li><a class="reference internal" href="#vertex-and-face-data">Vertex and Face Data</a><ul> +<li><a class="reference internal" href="#id2">Convex Meshes</a></li> +<li><a class="reference internal" href="#id3">Triangle Meshes</a></li> +<li><a class="reference internal" href="#id4">Height Fields</a></li> +<li><a class="reference internal" href="#heightfield-modification">Heightfield Modification</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Threading.html" + title="previous chapter">Threading</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="RigidBodyOverview.html" + title="next chapter">Rigid Body Overview</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" /> + <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="RigidBodyOverview.html" title="Rigid Body Overview" + >next</a></li> + <li class="right" > + <a href="Threading.html" title="Threading" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/GeometryQueries.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/GeometryQueries.html new file mode 100644 index 00000000..d99e844a --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/GeometryQueries.html @@ -0,0 +1,520 @@ +<!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>Geometry Queries — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Spatial Queries" href="SpatialQueries.html" /> + <link rel="prev" title="GPU Rigid Bodies" href="GPURigidBodies.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="SpatialQueries.html" title="Spatial Queries" + accesskey="N">next</a></li> + <li class="right" > + <a href="GPURigidBodies.html" title="GPU Rigid Bodies" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="geometry-queries"> +<span id="geometryqueries"></span><h1>Geometry Queries<a class="headerlink" href="#geometry-queries" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This chapter describes how to use PhysX' collision functionality with individual geometry objects. There are four main kinds of geometry queries:</p> +<ul class="simple"> +<li>raycasts ("raycast queries") test a ray against a geometry object.</li> +<li>sweeps ("sweep queries") move one geometry object along a line to find the first point of intersection with another geometry object.</li> +<li>overlaps ("overlap queries") determine whether two geometry objects intersect.</li> +<li>penetration depth computations ("minimal translational distance queries", abbreviated here to "MTD") test two overlapping geometry objects to find the direction along which they can be separated by the minimum distance.</li> +</ul> +<p>In addition, PhysX provides helpers to compute the AABB of a geometry object, and to compute the distance between a point and a geometry object.</p> +<p>In all of the following functions, a geometry object is defined by its shape (a <em>PxGeometry</em> structure) and its pose (a <em>PxTransform</em> structure). All transforms and vectors are interpreted as being in the same space, and the results are also returned in that space.</p> +</div> +<hr class="docutils" /> +<div class="section" id="raycasts"> +<h2>Raycasts<a class="headerlink" href="#raycasts" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/GeomQueryRaycast.png" src="../_images/GeomQueryRaycast.png" /> +<p>A raycast query traces a point along a line segment until it hits a geometry object. PhysX supports raycasts for all geometry types.</p> +<p>The following code illustrates how to use a raycast query:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastHit</span> <span class="n">hitInfo</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">maxHits</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> +<span class="n">PxHitFlags</span> <span class="n">hitFlags</span> <span class="o">=</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">ePOSITION</span><span class="o">|</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eNORMAL</span><span class="o">|</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDISTANCE</span><span class="o">|</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eUV</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">hitCount</span> <span class="o">=</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> + <span class="n">geom</span><span class="p">,</span> <span class="n">pose</span><span class="p">,</span> + <span class="n">maxDist</span><span class="p">,</span> + <span class="n">hitFlags</span><span class="p">,</span> + <span class="n">maxHits</span><span class="p">,</span> <span class="o">&</span><span class="n">hitInfo</span><span class="p">);</span> +</pre></div> +</div> +<p>The arguments are interpreted as follows:</p> +<ul class="simple"> +<li><em>origin</em> is the start point of the ray.</li> +<li><em>unitDir</em> is a unit vector defining the direction of the ray.</li> +<li><em>maxDist</em> is the maximum distance to search along the ray. It must be in the [0, inf) range. If the maximum distance is 0, a hit will only be returned if the ray starts inside a shape, as detailed below for each geometry.</li> +<li><em>geom</em> is the geometry to test against.</li> +<li><em>pose</em> is the pose of the geometry.</li> +<li><em>hitFlags</em> specifies the values that should be returned by the query, and options for processing the query.</li> +<li><em>maxHits</em> is the maximum number of hits to return.</li> +<li><em>hitInfo</em> specifies the <em>PxRaycastHit</em> structure(s) into which the raycast results will be stored.</li> +<li>The <em>anyHit</em> parameter is <strong>deprecated</strong>. It is equivalent to <em>PxHitFlag::eMESH_ANY</em>, which should be used instead.</li> +</ul> +<p>The returned result is the number of intersections found. For each intersection, a <em>PxRaycastHit</em> is populated. The fields of this structure are as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">actor</span><span class="p">;</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">position</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">normal</span><span class="p">;</span> +<span class="n">PxF32</span> <span class="n">distance</span><span class="p">;</span> +<span class="n">PxHitFlags</span> <span class="n">flags</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">faceIndex</span><span class="p">;</span> +<span class="n">PxF32</span> <span class="n">u</span><span class="p">,</span> <span class="n">v</span><span class="p">;</span> +</pre></div> +</div> +<p>Some fields are optional, and the flags field indicates which members have been filled with result values. The query will fill fields in the output structure if the corresponding flags were set in the input - for example, if the <em>PxHitFlag::ePOSITION</em> is set in the input hitFlags, the query will fill in the <em>PxRaycastHit::position</em> field, and set the <em>PxHitFlag::ePOSITION</em> flag in <em>PxRaycastHit::flags</em>. If the input flag is not set for a specific member, the result structure may or may not contain valid data for that member. Omitting the <em>eNORMAL</em> and <em>ePOSITION</em> flags in the input can sometimes result in faster queries.</p> +<p>For a raycast which is not initially intersecting the geometry object, the fields are populated as follows (optional fields are listed together with the flag that controls them):</p> +<ul class="simple"> +<li><em>actor</em> and <em>shape</em> are not filled (these fields are used only in scene-level raycasts, see <a class="reference internal" href="SceneQueries.html#scenequeries"><em>Scene Queries</em></a>).</li> +<li><em>position</em> (<em>PxHitFlag::ePOSITION</em>) is the position of the intersection.</li> +<li><em>normal</em> (<em>PxHitFlag::eNORMAL</em>) is the surface normal at the point of intersection.</li> +<li><em>distance</em> (<em>PxHitFlag::eDISTANCE</em>) is the distance along the ray at which the intersection was found.</li> +<li><em>flags</em> specifies which fields of the structure are valid.</li> +<li><em>faceIndex</em> is the index of the face which the ray hit. For triangle mesh and height field intersections, it is a triangle index. For convex mesh intersections it is a polygon index. For other shapes it is always set to 0xffffffff.</li> +<li><em>u</em> and <em>v</em> (<em>PxHitFlag::eUV</em>) are the barycentric coordinates of the intersection. These fields (and the flag) are supported only for meshes and heightfields.</li> +</ul> +<p>The position field is related to the barycentric coordinates via the following formula, where v0, v1 and v2 are the vertices from the hit triangle:</p> +<blockquote> +<div>position = (1 - u - v)*v0 + u*v1 + v*v2;</div></blockquote> +<p>This mapping is implemented in <em>PxTriangle::pointFromUV()</em>.</p> +<p>See <a class="reference internal" href="Geometry.html#geometry"><em>Geometry</em></a> for details of how to retrieve face and vertex data from triangle meshes, convex meshes and height fields using face and vertex indices.</p> +<p>Exceptions to the above behavior may apply if a ray starts inside an object, in which case PhysX may not be able to compute meaningful output values for some fields. In these cases the field will remain unmodified and the corresponding flag will not be set. Specific details vary by geometry type, and are described below.</p> +<p>The exact conditions for raycast intersections are as follows:</p> +<div class="section" id="raycasts-against-spheres-capsules-boxes-and-convex-meshes"> +<h3>Raycasts against Spheres, Capsules, Boxes and Convex Meshes<a class="headerlink" href="#raycasts-against-spheres-capsules-boxes-and-convex-meshes" title="Permalink to this headline">¶</a></h3> +<p>For solid objects (sphere, capsule, box, convex) at most 1 result is returned. If the ray origin is inside a solid object:</p> +<ul class="simple"> +<li>the reported hit distance is set to zero, and the <em>PxHitFlag::eDISTANCE</em> flag is set in the output.</li> +<li>the hit normal is set to be the opposite of the ray's direction, and the <em>PxHitFlag::eNORMAL</em> flag is set in the output.</li> +<li>the hit impact position is set to the ray's origin and the <em>PxHitFlag::ePOSITION</em> flag is set in the output.</li> +</ul> +<p>If the start or end point of a ray is very close to the surface of the object, it may be treated as being on either side of the surface.</p> +</div> +<div class="section" id="raycasts-against-planes"> +<h3>Raycasts against Planes<a class="headerlink" href="#raycasts-against-planes" title="Permalink to this headline">¶</a></h3> +<p>For raycasts, a plane is treated as an infinite single-sided quad that includes its boundary (note that this is not the same as for overlaps). At most one result is returned, and if the ray origin is behind the plane's surface, no hit will be reported even in case the ray intersects the plane.</p> +<p>If the start or end point of a ray is very close to the plane, it may be treated as being on either side of the plane.</p> +</div> +<div class="section" id="raycasts-against-triangle-meshes"> +<span id="raycasts-vs-meshes"></span><h3>Raycasts against Triangle Meshes<a class="headerlink" href="#raycasts-against-triangle-meshes" title="Permalink to this headline">¶</a></h3> +<p>Triangle meshes are treated as thin triangle surfaces rather than solid objects. They may be configured to return either an arbitrary hit, the closest hit, or multiple hits.</p> +<ul class="simple"> +<li>if maxHits is 1 and <em>PxHitFlag::eMESH_ANY</em> is not set, the query will return the closest intersection.</li> +<li>if maxHits is 1 and <em>PxHitFlag::eMESH_ANY</em> is set, the query will return an arbitrary intersection. Use this when it is sufficient to know whether or not the ray hit the mesh, e.g. for line-of-sight queries or shadow rays.</li> +<li>if maxHits is greater than 1, the query will return multiple intersections, up to maxHits. If more than maxHits intersection points exist, there is no guarantee that the results will include the closest. Use this for e.g. wall-piercing bullets that hit multiple triangles, or where special filtering is required. Note that <em>PxHitFlag::eMESH_MULTIPLE</em> must be used in this case.</li> +</ul> +<p>In general "any hit" queries are faster than "closest hit" queries, and "closest hit" queries are faster than "multiple hits" queries.</p> +<p>By default, back face hits (where the triangle's outward-facing normal has a positive dot product with the ray direction) are culled, and so for any triangle hit the reported normal will have a negative dot product with the ray direction. This behavior may be modified by the mesh instance's <em>PxMeshGeometryFlag::eDOUBLE_SIDED</em> flag and the query's <em>PxHitFlag::eMESH_BOTH_SIDES</em> flag:</p> +<ul class="simple"> +<li>if either <em>PxMeshGeometryFlag::eDOUBLE_SIDED</em> or <em>PxHitFlag::eMESH_BOTH_SIDES</em> is set, culling is disabled.</li> +<li>if <em>PxMeshGeometryFlag::eDOUBLE_SIDED</em> is set, the reported normal is reversed for a back face hit.</li> +</ul> +<p>For example a transparent glass window could be modeled as a double-sided mesh, so that a ray would hit either side with the reported normal facing opposite to the ray direction. A raycast tracing the path of a bullet that may penetrate the front side of a mesh and emerge from the back could use <em>eMESH_BOTH_SIDES</em> to find both front and back facing triangles even when the mesh is single-sided.</p> +<p>The following diagram shows what happens with different flags, for a single raycast intersecting a mesh in several places.</p> +<a class="reference internal image-reference" href="../_images/RayMeshDS_Permutations.png"><img alt="../_images/RayMeshDS_Permutations.png" src="../_images/RayMeshDS_Permutations.png" /></a> +<p>To use <em>PxHitFlag::eMESH_BOTH_SIDES</em> for selected meshes rather than all, set the flag inside the <em>PxQueryFilterCallback</em>.</p> +<p>If the start or end point of a ray is very close to the surface of a triangle, it may be treated as being on either side of the triangle.</p> +<p>If the start or end point of a ray is very close to the surface of a triangle, it may be treated as being on the either side of the triangle.</p> +</div> +<div class="section" id="raycasts-against-heightfields"> +<h3>Raycasts against Heightfields<a class="headerlink" href="#raycasts-against-heightfields" title="Permalink to this headline">¶</a></h3> +<ul class="simple"> +<li>Heightfields are treated the same way as triangle meshes with normals oriented (in shape space) in +y direction when thickness is <=0 and in -y direction when thickness is >0.</li> +<li>Double-sided heightfields are treated the same way as double sided triangle meshes.</li> +</ul> +</div> +</div> +<hr class="docutils" /> +<div class="section" id="overlaps"> +<h2>Overlaps<a class="headerlink" href="#overlaps" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/GeomQueryOverlap.png" src="../_images/GeomQueryOverlap.png" /> +<p>Overlap queries simply check whether two geometry objects overlap. One of the geometries must be a box, sphere, capsule or convex, and the other may be of any type.</p> +<p>The following code illustrates how to use an overlap query:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">isOverlapping</span> <span class="o">=</span> <span class="n">overlap</span><span class="p">(</span><span class="n">geom0</span><span class="p">,</span> <span class="n">pose0</span><span class="p">,</span> <span class="n">geom1</span><span class="p">,</span> <span class="n">pose1</span><span class="p">);</span> +</pre></div> +</div> +<p>Overlaps do not support hit flags and return only a boolean result.</p> +<ul class="simple"> +<li>A plane is treated as a solid half-space: that is, everything behind the plane is considered part of the volume.</li> +<li>Triangle meshes are treated as thin triangle surfaces rather than solid objects.</li> +<li>Heightfields are treated as triangle surface extruded by their thickness. Overlap geometries that do not intersect with the heightfield surface but are within the extruded space will report a hit.</li> +</ul> +<p>If more than a boolean result is needed for meshes and heightfields, use the <em>PxMeshQuery</em> API instead (see <a class="reference internal" href="#meshquery"><em>PxMeshQuery</em></a>).</p> +</div> +<hr class="docutils" /> +<div class="section" id="penetration-depth"> +<h2>Penetration Depth<a class="headerlink" href="#penetration-depth" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/GeomQueryPenetration.png" src="../_images/GeomQueryPenetration.png" /> +<p>When two objects are intersecting, PhysX can compute the minimal distance and direction by which the objects must be translated to separate them (this quantity is sometimes referred to as MTD, for <em>minimum translational distance</em>, as it is the vector of minimal length by which translation will separate the shapes). One geometry object must be a box, sphere, capsule or convex mesh, and the other may be of any type.</p> +<p>The following code illustrates how to use a penetration depth query:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">isPenetrating</span> <span class="o">=</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">computePenetration</span><span class="p">(</span><span class="n">direction</span><span class="p">,</span> <span class="n">depth</span><span class="p">,</span> + <span class="n">geom0</span><span class="p">,</span> <span class="n">pose0</span><span class="p">,</span> + <span class="n">geom1</span><span class="p">,</span> <span class="n">pose1</span><span class="p">);</span> +</pre></div> +</div> +<p>The arguments are interpreted as follows:</p> +<ul class="simple"> +<li><em>direction</em> is set to the direction in which the first object should be translated in order to depenetrate from the second.</li> +<li><em>distance</em> is set to the distance by which the first object should be translated in order to depenetrate from the second.</li> +<li><em>geom0</em> is the first geometry.</li> +<li><em>pose0</em> is the transform of the first geometry.</li> +<li><em>geom1</em> is the second geometry.</li> +<li><em>pose2</em> is the transform of the second geometry.</li> +</ul> +<p>The function returns true if the objects are penetrating, in which case it sets the direction and depth fields. Translating the first object by the depenetration vector D = direction * depth will separate the two objects. If the function returns true, the returned depth will always be positive or zero. If objects do not overlap, the function returns false, and the values of the direction and distance fields are undefined.</p> +<p>For simple (convex) shapes, returned results are accurate.</p> +<p>For meshes and heightfields, an iterative algorithm is used and dedicated functions are exposed in <em>PxExtensions</em>:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVec3</span> <span class="n">direction</span> <span class="o">=</span> <span class="n">PxComputeMeshPenetration</span><span class="p">(</span><span class="n">direction</span><span class="p">,</span> <span class="n">depth</span><span class="p">,</span> + <span class="n">geom</span><span class="p">,</span> <span class="n">geomPose</span><span class="p">,</span> + <span class="n">meshGeom</span><span class="p">,</span> <span class="n">meshPose</span><span class="p">,</span> + <span class="n">maxIter</span><span class="p">,</span> <span class="n">nb</span><span class="p">);</span> + +<span class="n">PxVec3</span> <span class="n">direction</span> <span class="o">=</span> <span class="n">PxComputeHeightFieldPenetration</span><span class="p">(</span><span class="n">direction</span><span class="p">,</span> <span class="n">depth</span> + <span class="n">geom</span><span class="p">,</span> <span class="n">geomPose</span><span class="p">,</span> + <span class="n">heightFieldGeom</span><span class="p">,</span> <span class="n">heightFieldPose</span><span class="p">,</span> + <span class="n">maxIter</span><span class="p">,</span> <span class="n">nb</span><span class="p">);</span> +</pre></div> +</div> +<p>Here, <em>maxIter</em> is the maximum number of iterations for the algorithm, and <em>nb</em> is an optional output argument which will be set to the number of iterations performed. If no overlap is detected, <em>nb</em> is set to zero. The code will attempt at most maxIter iterations but may exit earlier if a depenetration vector is found. Usually maxIter = 4 gives good results.</p> +<p>These functions only compute an approximate depenetration vector, and work best when the amount of overlap between the geometry object and the mesh/heightfield is small. In particular, an intersection with a triangle will be ignored when the object's center is behind the triangle, and if this holds for all intersecting triangles then no overlap is detected, and the functions do not compute an MTD vector.</p> +</div> +<hr class="docutils" /> +<div class="section" id="sweeps"> +<h2>Sweeps<a class="headerlink" href="#sweeps" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/GeomQuerySweep.png" src="../_images/GeomQuerySweep.png" /> +<p>A sweep query traces one geometry object through space to find the impact point on a second geometry object, and reports information concerning the impact point if one is found. PhysX only supports sweep queries where the first geometry object (the one that is traced through space) is a sphere, box, capsule or convex geometry. The second geometry object may be of any type.</p> +<p>The following code illustrates how to use a sweep query:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSweepHit</span> <span class="n">hitInfo</span><span class="p">;</span> +<span class="n">PxHitFlags</span> <span class="n">hitFlags</span> <span class="o">=</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">ePOSITION</span><span class="o">|</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eNORMAL</span><span class="o">|</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDISTANCE</span><span class="p">;</span> +<span class="n">PxReal</span> <span class="n">inflation</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">hitCount</span> <span class="o">=</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">sweep</span><span class="p">(</span><span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDist</span><span class="p">,</span> + <span class="n">geomToSweep</span><span class="p">,</span> <span class="n">poseToSweep</span><span class="p">,</span> + <span class="n">geomSweptAgainst</span><span class="p">,</span> <span class="n">poseSweptAgainst</span><span class="p">,</span> + <span class="n">hitInfo</span><span class="p">,</span> + <span class="n">hitFlags</span><span class="p">,</span> + <span class="n">inflation</span><span class="p">);</span> +</pre></div> +</div> +<p>The arguments are interpreted as follows:</p> +<ul class="simple"> +<li><em>unitDir</em> is a unit vector defining the direction of the sweep.</li> +<li><em>maxDist</em> is the maximum distance to search along the sweep. It must be in the [0, inf) range, and is clamped by SDK code to at most <em>PX_MAX_SWEEP_DISTANCE</em>. A sweep of length 0 is equivalent to an overlap check.</li> +<li><em>geomToSweep</em> is the geometry to sweep. Supported geometries are: box, sphere, capsule or convex mesh.</li> +<li><em>poseToSweep</em> is the initial pose of the geometry to sweep.</li> +<li><em>geomSweptAgainst</em> is the geometry to sweep against (any geometry type can be used here).</li> +<li><em>poseSweptAgainst</em> is the pose of the geometry to sweep against.</li> +<li><em>hitInfo</em> is the returned result. A sweep will return at most one hit.</li> +<li><em>hitFlags</em> determines how the sweep is processed, and which data is returned if an impact is found.</li> +<li><em>inflation</em> inflates the first geometry with a shell extending outward from the object surface, making any corners rounded. It can be used to ensure a minimum margin of space is kept around the geometry when using sweeps to test whether movement is possible.</li> +</ul> +<p>As with raycasts, fields will be filled in the output structure if the corresponding flags were set in the input hitFlags. The fields of PxSweepHit are as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">actor</span><span class="p">;</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">position</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">normal</span><span class="p">;</span> +<span class="n">PxF32</span> <span class="n">distance</span><span class="p">;</span> +<span class="n">PxHitFlags</span> <span class="n">flags</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">faceIndex</span><span class="p">;</span> +</pre></div> +</div> +<ul class="simple"> +<li><em>actor</em> and <em>shape</em> are not filled (these fields are used only in scene-level sweeps, see <a class="reference internal" href="SceneQueries.html#scenequeries"><em>Scene Queries</em></a>).</li> +<li><em>position</em> (<em>PxHitFlag::ePOSITION</em>) is the position of the intersection. When there are multiple impact points, such as two boxes meeting face-to-face, PhysX will select one point arbitrarily. More detailed information for meshes or height fields may be obtained using the functions in <a class="reference internal" href="#meshquery"><em>PxMeshQuery</em></a>.</li> +<li><em>normal</em> (<em>PxHitFlag::eNORMAL</em>) is the surface normal at the point of impact. It is a unit vector, pointing outwards from the hit object and backwards along the sweep direction (in the sense that the dot product between the sweep direction and the impact normal is negative).</li> +<li><em>distance</em> (<em>PxHitFlag::eDISTANCE</em>) is the distance along the ray at which the intersection was found.</li> +<li><em>flags</em> specifies which fields of the structure are valid.</li> +<li><em>faceIndex</em> is the index of the face hit by the sweep. This is a face from the hit object, not from the swept object. For triangle mesh and height field intersections, it is a triangle index. For convex mesh intersections it is a polygon index. For other shapes it is always set to 0xffffffff. For convex meshes the face index computation is rather expensive. The face index computation can be disabled by not providing the scene query hit flag <em>PxHitFlag::eFACE_INDEX</em>. If needed the face index can also be computed externally using the function <em>PxFindFaceIndex</em> which is part of the PhysX extensions library.</li> +</ul> +<p>Unlike raycasts, u,v coordinates are not supported for sweeps.</p> +<p>For the geometry object swept against:</p> +<ul class="simple"> +<li>A plane is treated as a solid half-space: that is, everything behind the plane is considered part of the volume to sweep against.</li> +<li>The same backface-culling rules as for raycasts apply for sweeps, with the notable difference that <em>eMESH_MULTIPLE</em> is not supported.</li> +</ul> +<div class="section" id="initial-overlaps"> +<h3>Initial Overlaps<a class="headerlink" href="#initial-overlaps" title="Permalink to this headline">¶</a></h3> +<p>Similarly to a raycast starting inside an object, a sweep may start with the two geometries initially intersecting. By default PhysX will detect and report the overlap. Use <em>PxSweepHit::hadInitialOverlap()</em> to see if the hit was generated by an initial overlap.</p> +<p>For triangle meshes and height fields, backface culling is performed before overlap checks, and thus no initial overlap is reported if a triangle is culled.</p> +<p>Depending on the value of <em>PxHitFlag::eMTD</em>, PhysX may also calculate the MTD. If <em>PxHitFlag::eMTD</em> is not set:</p> +<ul class="simple"> +<li>the distance is set to zero, and the <em>PxHitFlag::eDISTANCE</em> flag is set in the <em>PxSweepHit</em> result structure.</li> +<li>the normal is set to be the opposite of the sweep direction, and the <em>PxHitFlag::eNORMAL</em> flag is set in the <em>PxSweepHit</em> result structure.</li> +<li>the position is undefined, and the <em>PxHitFlag::ePOSITION</em> flag is <em>not</em> set in the <em>PxSweepHit</em> result structure.</li> +<li>the faceIndex is a face from the second geometry object. For a heightfield or triangle mesh, it is the index of the first overlapping triangle found. For other geometry types, the index is set to 0xffffffff.</li> +</ul> +<p>If <em>PxHitFlag::eMTD</em> is set, the hit results are defined as follows:</p> +<ul class="simple"> +<li>the distance is set to the penetration depth, and the <em>PxHitFlag::eDISTANCE</em> flag is set in the <em>PxSweepHit</em> result structure.</li> +<li>the normal is set to the depenetration direction, and the <em>PxHitFlag::eNORMAL</em> flag is set in the <em>PxSweepHit</em> result structure.</li> +<li>the position is a point on the sweep geometry object (i.e. the first geometry argument) and the <em>PxHitFlag::ePOSITION</em> flag is set in the <em>PxSweepHit</em> result structure.</li> +<li>the faceIndex is a face from the second geometry object:</li> +</ul> +<blockquote> +<div><ul class="simple"> +<li>For triangle meshes and heightfields it is the last penetrated triangle found during the last iteration of the depenetration algorithm.</li> +<li>For other geometry types, the index is set to 0xffffffff.</li> +</ul> +</div></blockquote> +<p>This flag will incur additional processing overhead in the case of an initial overlap. In addition, the following restrictions apply:</p> +<ul class="simple"> +<li><em>PxHitFlag::eMTD</em> is incompatible with <em>PxHitFlag::ePRECISE_SWEEP</em> and <em>PxHitFlag::eASSUME_NO_INITIAL_OVERLAP</em> (see below). Using <em>PxHitFlag::eMTD</em> in conjunction with either of these flags will result in a warning being issued and the flag(s) that are incompatible with <em>PxHitFlag::eMTD</em> being ignored.</li> +</ul> +<p>Testing for initial overlaps sometimes uses a specialized code path and incurs a performance penalty. If is it possible to guarantee that geometry objects are not initially overlapping, the check for overlaps can be suppressed with <em>PxHitFlag::eASSUME_NO_INITIAL_OVERLAP</em>. There are some restrictions on the use of this flag (also, see <a class="reference internal" href="#sweep-pitfalls"><em>Pitfalls</em></a>)</p> +<ul class="simple"> +<li>Using <em>PxHitFlag::eASSUME_NO_INITIAL_OVERLAP</em> flag when the geometries initially overlap produces undefined behavior.</li> +<li><em>PxHitFlag::eASSUME_NO_INITIAL_OVERLAP</em> in combination with zero sweep distance produces a warning and undefined behavior.</li> +</ul> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">sweeps with <em>PxHitFlag::eMTD</em> use two kinds of backface culling for triangles. First, the triangles are culled based on sweep direction to determine whether there is an overlap. If an overlap is detected, they are further culled by whether the centroid is behind the triangle, and if no triangles are found, the direction will be set opposite to the sweep direction and the distance to 0.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">in most cases, translating the first geometry object by -normal*distance will separate the objects. However, an iterative depenetration algorithm is used to find the MTD for triangle meshes and height fields, and the MTD result may not provide complete depenetration from the mesh in extreme cases. In this case the query should be called a second time after the translation has been applied.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">a known issue in PhysX 3.3 is that the face index for a sweep against a convex mesh is undefined when the eMTD flag is not set.</p> +</div> +</div> +<div class="section" id="precise-sweeps"> +<h3>Precise Sweeps<a class="headerlink" href="#precise-sweeps" title="Permalink to this headline">¶</a></h3> +<p><em>PxHitFlag::ePRECISE_SWEEP</em> enables more accurate sweep code (by default a potentially faster but less accurate solution is used). The <em>ePRECISE_SWEEP</em> flag is not compatible with the inflation parameter, or with the flag <em>PxHitFlag::eMTD</em>.</p> +</div> +<div class="section" id="sweeps-against-height-fields"> +<h3>Sweeps against Height Fields<a class="headerlink" href="#sweeps-against-height-fields" title="Permalink to this headline">¶</a></h3> +<ul> +<li><p class="first">Height fields are treated as thin triangle surfaces rather than solid objects.</p> +</li> +<li><p class="first">Thickness magnitude has no effect on initial overlap detection or point of impact.</p> +</li> +<li><p class="first">For single-sided height fields the normal of the hit will face in +y local space direction if thickness is < 0 and -y when thickness is > 0.</p> +</li> +<li><p class="first">Height fields are treated as double sided if either one of eDOUBLE_SIDED or eMESH_BOTH_SIDES flags are used.</p> +<blockquote> +<div><ul class="simple"> +<li>The returned hit normal will always face the sweep direction.</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">eMESH_ANY flag has no effect.</p> +</li> +<li><p class="first">ePRECISE_SWEEP flag has no effect.</p> +</li> +</ul> +</div> +<div class="section" id="pitfalls"> +<span id="sweep-pitfalls"></span><h3>Pitfalls<a class="headerlink" href="#pitfalls" title="Permalink to this headline">¶</a></h3> +<p>There are some pitfalls to be aware of when using sweeps:</p> +<ul class="simple"> +<li>Due to numerical precision issues, incorrect results may be returned when the objects have very large size disparities.</li> +<li>Due to algorithmic differences, a sweep query may detect a different set of initially overlapping shapes than an overlap query. In particular, it is not sufficient to perform an overlap check in order to determine the safety of the <em>PxHitFlag::eIGNORE_INITIAL_OVERLAP</em> flag. Applications that need consistent overlap/sweep/penetration depth information should use sweep checks with initial overlap testing and the <em>PxHitFlag::eMTD</em> flag.</li> +</ul> +</div> +</div> +<hr class="docutils" /> +<div class="section" id="additional-pxgeometryquery-functions"> +<h2>Additional PxGeometryQuery functions<a class="headerlink" href="#additional-pxgeometryquery-functions" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/GeomQueryPointDistance.png" src="../_images/GeomQueryPointDistance.png" /> +<p>The following function computes the distance between a point and a geometry object. Only solid objects (box, sphere, capsule, convex) are supported:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxReal</span> <span class="n">dist</span> <span class="o">=</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">pointDistance</span><span class="p">(</span><span class="n">point</span><span class="p">,</span> <span class="n">geom</span><span class="p">,</span> <span class="n">pose</span><span class="p">,</span> <span class="n">closestPoint</span><span class="p">);</span> +</pre></div> +</div> +<p><em>closestPoint</em> is an optional output argument which returns the closest point.</p> +<img alt="../_images/GeomQueryWorldBounds.png" src="../_images/GeomQueryWorldBounds.png" /> +<p>The following function computes the axis-aligned bounding box (AABB) enclosing a geometry object, given its pose:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxBounds3</span> <span class="n">bounds</span> <span class="o">=</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">getWorldBounds</span><span class="p">(</span><span class="n">geom</span><span class="p">,</span> <span class="n">pose</span><span class="p">,</span> <span class="n">inflation</span><span class="p">);</span> +</pre></div> +</div> +<p>The bounding box is scaled by the <em>inflation</em> value, which defaults to 1.01f if not explicitly specified.</p> +<hr class="docutils" /> +</div> +<div class="section" id="pxmeshquery"> +<span id="meshquery"></span><h2>PxMeshQuery<a class="headerlink" href="#pxmeshquery" title="Permalink to this headline">¶</a></h2> +<p>PhysX provides additional functionality for obtaining multiple results for triangle mesh and height field overlaps, and for sweeping against arrays of triangles. Only boxes, spheres and capsules may be tested against meshes or heightfields using these functions.</p> +<div class="section" id="mesh-overlaps"> +<h3>Mesh Overlaps<a class="headerlink" href="#mesh-overlaps" title="Permalink to this headline">¶</a></h3> +<p>The following code illustrates how to process the mesh triangles touching a given spherical volume:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="n">triangleIndexBuffer</span><span class="p">[</span><span class="n">bufferSize</span><span class="p">];</span> +<span class="n">PxU32</span> <span class="n">startIndex</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">bufferOverflowOccured</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">nbTriangles</span> <span class="o">=</span> <span class="n">PxMeshQuery</span><span class="o">::</span><span class="n">findOverlapTriangleMesh</span><span class="p">(</span><span class="n">sphereGeom</span><span class="p">,</span> <span class="n">spherePose</span><span class="p">,</span> + <span class="n">meshGeom</span><span class="p">,</span> <span class="n">meshPose</span><span class="p">,</span> + <span class="n">triangleIndexBuffer</span><span class="p">,</span> <span class="n">bufferSize</span><span class="p">,</span> + <span class="n">startIndex</span><span class="p">,</span> <span class="n">bufferOverflowOccured</span><span class="p">);</span> + +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">nbTriangles</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">PxTriangle</span> <span class="n">tri</span><span class="p">;</span> + <span class="n">PxU32</span> <span class="n">vertexIndices</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span> + <span class="n">PxMeshQuery</span><span class="o">::</span><span class="n">getTriangle</span><span class="p">(</span><span class="n">meshGeom</span><span class="p">,</span> <span class="n">meshPose</span><span class="p">,</span> <span class="n">triangleIndexBuffer</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">tri</span><span class="p">,</span> <span class="n">vertexIndices</span><span class="p">);</span> + + <span class="p">...</span> <span class="c1">// process triangle info</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The <em>findOverlapTriangleMesh</em> method is used to extract the indices of the triangles:</p> +<ul class="simple"> +<li><em>sphereGeom</em> and <em>spherePose</em> specify the region to test for overlap.</li> +<li><em>meshGeom</em> and <em>meshPose</em> specify the mesh and its pose.</li> +<li><em>triangleIndexBuffer</em> and <em>triangleSize</em> specify the output buffer and its size.</li> +<li><em>startIndex</em> is used to restart the query if the buffer size is exceeded. In this case, to query for more triangles set this parameter to the number retrieved so far.</li> +<li><em>bufferOverflowOccured</em> is set if more triangles would be returned from the query than would fit in the buffer.</li> +</ul> +<p>Similar query functionality exists for height fields.</p> +</div> +<div class="section" id="sweeps-against-triangles"> +<h3>Sweeps against Triangles<a class="headerlink" href="#sweeps-against-triangles" title="Permalink to this headline">¶</a></h3> +<p>Sometimes, for example, when using the mesh overlap API, it is convenient to be able to sweep against groups of triangles. PhysX provides a function specifically for this purpose, with the following signature:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="nf">sweep</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">unitDir</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxReal</span> <span class="n">distance</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxGeometry</span><span class="o">&</span> <span class="n">geom</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">pose</span><span class="p">,</span> + <span class="n">PxU32</span> <span class="n">triangleCount</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxTriangle</span><span class="o">*</span> <span class="n">triangles</span><span class="p">,</span> + <span class="n">PxSweepHit</span><span class="o">&</span> <span class="n">sweepHit</span><span class="p">,</span> + <span class="n">PxHitFlags</span> <span class="n">hitFlags</span> <span class="o">=</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxU32</span><span class="o">*</span> <span class="n">cachedIndex</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxReal</span> <span class="n">inflation</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">,</span> + <span class="kt">bool</span> <span class="n">doubleSided</span> <span class="o">=</span> <span class="nb">false</span><span class="p">);</span> +</pre></div> +</div> +<p>The arguments are interpreted as follows:</p> +<ul class="simple"> +<li><em>unitDir</em>, <em>distance</em>, <em>geom</em> and <em>pose</em> function identically to the first four parameters of PxGeometryQuery::sweep(). <em>distance</em> is clamped to PX_MAX_SWEEP_DISTANCE.</li> +<li><em>triangleCount</em> is the number of triangles contained in the buffer against which to sweep.</li> +<li><em>triangles</em> is the buffer of triangles.</li> +<li><em>hitFlags</em> specifies the required information in the output.</li> +<li><em>cachedIndex</em>, if set, specifies the index of a triangle to test first. This can be a useful optimization when repeatedly sweeping against the same set of triangles.</li> +<li><em>inflation</em> functions identically to the inflation parameter of PxGeometryQuery::sweep().</li> +<li><em>doubleSided</em> indicates whether the input triangles are double-sided or not. This is equivalent to the <em>PxMeshGeometryFlag::eDOUBLE_SIDED</em> flag - that is, it suppresses backface culling, and for any hit the returned normal faces opposite to the sweep direction (see <a class="reference internal" href="#raycasts-vs-meshes"><em>Raycasts against Triangle Meshes</em></a>).</li> +</ul> +<p>This function has extra limitations compared to the other sweep queries:</p> +<ul class="simple"> +<li>the geometry type must be either a sphere, a capsule or a box. Convex geometry is not supported.</li> +<li>the function returns a single hit. Multiple hits (and in particular PxHitFlag::eMESH_MULTIPLE) are not supported.</li> +<li>The function always returns the closest hit.</li> +<li>The only supported flags are PxHitFlag::eDEFAULT, PxHitFlag::eASSUME_NO_INITIAL_OVERLAP, PxHitFlag::ePRECISE_SWEEP, PxHitFlag::eMESH_BOTH_SIDES and PxHitFlag::eMESH_ANY.</li> +</ul> +<p>The function tests each input triangle in the order they are given. By default, the function will test all triangles and return the closest sweep hit (if a hit has been found). If PxHitFlag::eMESH_ANY is used, the function will return as soon as a hit is found (skipping the remaining untested triangles). This flag can also be used to emulate PxHitFlag::eMESH_MULTIPLE, by calling the function repeatedly with PxHitFlag::eMESH_ANY, using as a starting point the previously returned hit triangle (whose index, between 0 and 'triangleCount', is available in sweepHit.faceIndex).</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Geometry Queries</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#raycasts">Raycasts</a><ul> +<li><a class="reference internal" href="#raycasts-against-spheres-capsules-boxes-and-convex-meshes">Raycasts against Spheres, Capsules, Boxes and Convex Meshes</a></li> +<li><a class="reference internal" href="#raycasts-against-planes">Raycasts against Planes</a></li> +<li><a class="reference internal" href="#raycasts-against-triangle-meshes">Raycasts against Triangle Meshes</a></li> +<li><a class="reference internal" href="#raycasts-against-heightfields">Raycasts against Heightfields</a></li> +</ul> +</li> +<li><a class="reference internal" href="#overlaps">Overlaps</a></li> +<li><a class="reference internal" href="#penetration-depth">Penetration Depth</a></li> +<li><a class="reference internal" href="#sweeps">Sweeps</a><ul> +<li><a class="reference internal" href="#initial-overlaps">Initial Overlaps</a></li> +<li><a class="reference internal" href="#precise-sweeps">Precise Sweeps</a></li> +<li><a class="reference internal" href="#sweeps-against-height-fields">Sweeps against Height Fields</a></li> +<li><a class="reference internal" href="#pitfalls">Pitfalls</a></li> +</ul> +</li> +<li><a class="reference internal" href="#additional-pxgeometryquery-functions">Additional PxGeometryQuery functions</a></li> +<li><a class="reference internal" href="#pxmeshquery">PxMeshQuery</a><ul> +<li><a class="reference internal" href="#mesh-overlaps">Mesh Overlaps</a></li> +<li><a class="reference internal" href="#sweeps-against-triangles">Sweeps against Triangles</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="GPURigidBodies.html" + title="previous chapter">GPU Rigid Bodies</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="SpatialQueries.html" + title="next chapter">Spatial Queries</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" /> + <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="SpatialQueries.html" title="Spatial Queries" + >next</a></li> + <li class="right" > + <a href="GPURigidBodies.html" title="GPU Rigid Bodies" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/HelloWorld.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/HelloWorld.html new file mode 100644 index 00000000..ea02576c --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/HelloWorld.html @@ -0,0 +1,143 @@ +<!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>Snippets — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Building with PhysX" href="BuildingWithPhysX.html" /> + <link rel="prev" title="Welcome to PhysX" href="Introduction.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="BuildingWithPhysX.html" title="Building with PhysX" + accesskey="N">next</a></li> + <li class="right" > + <a href="Introduction.html" title="Welcome to PhysX" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="snippets"> +<span id="helloworld"></span><h1>Snippets<a class="headerlink" href="#snippets" title="Permalink to this headline">¶</a></h1> +<div class="section" id="what-are-physx-snippets"> +<h2>What are PhysX Snippets?<a class="headerlink" href="#what-are-physx-snippets" title="Permalink to this headline">¶</a></h2> +<p>In the context of the PhysX SDK, a 'Snippet' is a simple, minimalistic code sample. +PhysX-SDK version 3.3.0 offers a collection of Snippets to illustrate usage of the PhysX API in a +concise format, free from the complexity of a sample framework or game engine. The Snippets folder is +in the top-level directory of the PhysX SDK, alongside directories for Documentation, Include, Samples, etc.</p> +<dl class="docutils"> +<dt>The folder {SDK Root}/Snippets/compiler/{platform} contains the Snippets solution file, e.g.</dt> +<dd>Snippets/compiler/vc10win64/Snippets.sln</dd> +</dl> +<p>Although a few of the Snippets support rendering, ( Win32, Win64, OSX and Linux only ) most Snippets do not provide rendering, require no input, +and provide only limited output through messages. Although Snippets can be run from a command prompt or by double-clicking the executable +icon, the best way to explore Snippets is by viewing the code in the Visual Studio IDE, and running the program in the debugger.</p> +</div> +<div class="section" id="helloworld-physx-basics"> +<span id="helloworldbasics"></span><h2>HelloWorld: PhysX Basics<a class="headerlink" href="#helloworld-physx-basics" title="Permalink to this headline">¶</a></h2> +<p>SnippetHelloWorld illustrates basic use of PhysX, from startup to shutdown of a simple scene, and +is a good place to start learning the PhysX API. The simplest Snippets comprise a single source file, but SnippetHelloWorld, +among others, supports optional rendering through a second source file. SnippetHelloWorld creates a number of box stacks on +a plane, and if rendering is enabled, allows the user to create new stacks and fire a ball from the camera position.</p> +<p>The primary code for SnippetHelloWorld is found in {SDK Root}/Snippets/SnippetHelloWorld/SnippetHelloWorld.cpp.</p> +</div> +<div class="section" id="using-physx-visual-debugger-with-snippethelloworld"> +<span id="pvdandhelloworld"></span><h2>Using PhysX Visual Debugger with SnippetHelloWorld<a class="headerlink" href="#using-physx-visual-debugger-with-snippethelloworld" title="Permalink to this headline">¶</a></h2> +<p>As is the case with any Snippet built against PROFILE, CHECKED or DEBUG configurations of the PhysX runtime, +HelloWorld will automatically connect to the PhysX Visual Debugger if that application is already running +when the Snippet executable is launched. For Snippets without rendering, PVD provides an easy way to visualize +the contents of the PhysX scene presented in the Snippet. In the screenshot image below, PhysX Visual Debugger appears on +the right hand side, while Visual Studio and Snippet Hello World are on the left.</p> +<img alt="../_images/HelloWorld.png" src="../_images/HelloWorld.png" /> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Snippets</a><ul> +<li><a class="reference internal" href="#what-are-physx-snippets">What are PhysX Snippets?</a></li> +<li><a class="reference internal" href="#helloworld-physx-basics">HelloWorld: PhysX Basics</a></li> +<li><a class="reference internal" href="#using-physx-visual-debugger-with-snippethelloworld">Using PhysX Visual Debugger with SnippetHelloWorld</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Introduction.html" + title="previous chapter">Welcome to PhysX</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="BuildingWithPhysX.html" + title="next chapter">Building with PhysX</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" /> + <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="BuildingWithPhysX.html" title="Building with PhysX" + >next</a></li> + <li class="right" > + <a href="Introduction.html" title="Welcome to PhysX" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Index.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Index.html new file mode 100644 index 00000000..9d81ed92 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Index.html @@ -0,0 +1,797 @@ +<!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>User's Guide — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="next" title="Welcome to PhysX" href="Introduction.html" /> + <link rel="prev" title="NVIDIA® PhysX® SDK 3.4.0 Documentation" href="../Index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Introduction.html" title="Welcome to PhysX" + accesskey="N">next</a></li> + <li class="right" > + <a href="../Index.html" title="NVIDIA® PhysX® SDK 3.4.0 Documentation" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="user-s-guide"> +<h1>User's Guide<a class="headerlink" href="#user-s-guide" title="Permalink to this headline">¶</a></h1> +<img alt="../_images/PhysXlogo1.png" src="../_images/PhysXlogo1.png" /> +<p>Built October 24, 2016</p> +<p>Contents:</p> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="Introduction.html">Welcome to PhysX</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Introduction.html#about-this-user-guide">About this User Guide</a></li> +<li class="toctree-l2"><a class="reference internal" href="Introduction.html#physics-vs-physx">Physics vs. PhysX</a></li> +<li class="toctree-l2"><a class="reference internal" href="Introduction.html#world-and-objects">World and Objects</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="HelloWorld.html">Snippets</a><ul> +<li class="toctree-l2"><a class="reference internal" href="HelloWorld.html#what-are-physx-snippets">What are PhysX Snippets?</a></li> +<li class="toctree-l2"><a class="reference internal" href="HelloWorld.html#helloworld-physx-basics">HelloWorld: PhysX Basics</a></li> +<li class="toctree-l2"><a class="reference internal" href="HelloWorld.html#using-physx-visual-debugger-with-snippethelloworld">Using PhysX Visual Debugger with SnippetHelloWorld</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="BuildingWithPhysX.html">Building with PhysX</a><ul> +<li class="toctree-l2"><a class="reference internal" href="BuildingWithPhysX.html#build-settings">Build Settings</a></li> +<li class="toctree-l2"><a class="reference internal" href="BuildingWithPhysX.html#build-configurations">Build Configurations</a></li> +<li class="toctree-l2"><a class="reference internal" href="BuildingWithPhysX.html#header-files">Header Files</a></li> +<li class="toctree-l2"><a class="reference internal" href="BuildingWithPhysX.html#libraries">Libraries</a></li> +<li class="toctree-l2"><a class="reference internal" href="BuildingWithPhysX.html#redistribution">Redistribution</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="API.html">The PhysX API</a><ul> +<li class="toctree-l2"><a class="reference internal" href="API.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#memory-management">Memory Management</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#error-reporting">Error Reporting</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#math-classes">Math Classes</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#connecting-physx-objects-with-user-application-objects">Connecting PhysX Objects with User Application Objects</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#type-casting">Type Casting</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#reference-counting">Reference Counting</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#using-different-units">Using Different Units</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#assertions">Assertions</a></li> +<li class="toctree-l2"><a class="reference internal" href="API.html#determinism">Determinism</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Startup.html">Startup and Shutdown</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#foundation-and-physics">Foundation and Physics</a></li> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#cooking">Cooking</a></li> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#extensions">Extensions</a></li> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#optional-sdk-components">Optional SDK Components</a></li> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#delay-loading-dlls">Delay-Loading DLLs</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Startup.html#physxcommon-dll-and-psfoundation-dll-load">PhysXCommon DLL and PsFoundation DLL load</a></li> +<li class="toctree-l3"><a class="reference internal" href="Startup.html#pxdelayloadhook">PxDelayLoadHook</a></li> +<li class="toctree-l3"><a class="reference internal" href="Startup.html#physxcommon-secure-load">PhysXCommon Secure Load</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Startup.html#shutting-down">Shutting Down</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Threading.html">Threading</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Threading.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Threading.html#data-access-from-multiple-threads">Data Access from Multiple Threads</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#scene-locking">Scene Locking</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#locking-semantics">Locking Semantics</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#locking-best-practices">Locking Best Practices</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Threading.html#asynchronous-simulation">Asynchronous Simulation</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#double-buffering">Double Buffering</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#events-involving-removed-objects">Events involving removed objects</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#support">Support</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#memory-considerations">Memory Considerations</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Threading.html#multithreaded-simulation">Multithreaded Simulation</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#taskmanager">TaskManager</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#cpudispatcher">CpuDispatcher</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#cpudispatcher-implementation-guidelines">CpuDispatcher Implementation Guidelines</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#basetask">BaseTask</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#task">Task</a></li> +<li class="toctree-l3"><a class="reference internal" href="Threading.html#lightcputask">LightCpuTask</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Geometry.html">Geometry</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Geometry.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Geometry.html#geometry-types">Geometry Types</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#spheres">Spheres</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#capsules">Capsules</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#boxes">Boxes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#planes">Planes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#convex-meshes">Convex Meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#convex-mesh-cooking">Convex Mesh cooking</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#triangle-meshes">Triangle Meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#height-fields">Height Fields</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Geometry.html#mesh-scaling">Mesh Scaling</a></li> +<li class="toctree-l2"><a class="reference internal" href="Geometry.html#pxgeometryholder">PxGeometryHolder</a></li> +<li class="toctree-l2"><a class="reference internal" href="Geometry.html#vertex-and-face-data">Vertex and Face Data</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#id2">Convex Meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#id3">Triangle Meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#id4">Height Fields</a></li> +<li class="toctree-l3"><a class="reference internal" href="Geometry.html#heightfield-modification">Heightfield Modification</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="RigidBodyOverview.html">Rigid Body Overview</a><ul> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyOverview.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyOverview.html#rigid-body-object-model">Rigid Body Object Model</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyOverview.html#the-simulation-loop">The Simulation Loop</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="RigidBodyCollision.html">Rigid Body Collision</a><ul> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#shapes">Shapes</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#simulation-shapes-and-scene-query-shapes">Simulation Shapes and Scene Query Shapes</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#kinematic-triangle-meshes-planes-heighfields">Kinematic Triangle Meshes (Planes, Heighfields)</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#broad-phase-algorithms">Broad-phase Algorithms</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#regions-of-interest">Regions of Interest</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#broad-phase-callback">Broad-phase Callback</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#collision-filtering">Collision Filtering</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#aggregates">Aggregates</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#creating-an-aggregate">Creating an Aggregate</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#populating-an-aggregate">Populating an Aggregate</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#releasing-an-aggregate">Releasing an Aggregate</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#amortizing-insertion">Amortizing Insertion</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#trigger-shapes">Trigger Shapes</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyCollision.html#interactions">Interactions</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="RigidBodyDynamics.html">Rigid Body Dynamics</a><ul> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#velocity">Velocity</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#mass-properties">Mass Properties</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#applying-forces-and-torques">Applying Forces and Torques</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#gravity">Gravity</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#friction-and-restitution">Friction and Restitution</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#sleeping">Sleeping</a><ul> +<li class="toctree-l3"><a class="reference internal" href="RigidBodyDynamics.html#sleep-state-change-events">Sleep state change events</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#kinematic-actors">Kinematic Actors</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#active-transforms">Active Transforms</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#active-actors">Active Actors</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#dominance">Dominance</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#solver-iterations">Solver Iterations</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#immediate-mode">Immediate Mode</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#enhanced-determinism">Enhanced Determinism</a></li> +<li class="toctree-l2"><a class="reference internal" href="RigidBodyDynamics.html#axis-locking">Axis locking</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Simulation.html">Simulation</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#callback-sequence">Callback Sequence</a></li> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#simulation-memory">Simulation memory</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Simulation.html#scene-limits">Scene Limits</a></li> +<li class="toctree-l3"><a class="reference internal" href="Simulation.html#k-data-blocks">16K Data Blocks</a></li> +<li class="toctree-l3"><a class="reference internal" href="Simulation.html#scratch-buffer">Scratch Buffer</a></li> +<li class="toctree-l3"><a class="reference internal" href="Simulation.html#in-place-serialization">In-place Serialization</a></li> +<li class="toctree-l3"><a class="reference internal" href="Simulation.html#pvd-integration">PVD Integration</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#completion-tasks">Completion Tasks</a></li> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#synchronizing-with-other-threads">Synchronizing with Other Threads</a></li> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#substepping">Substepping</a></li> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#split-sim">Split sim</a></li> +<li class="toctree-l2"><a class="reference internal" href="Simulation.html#split-fetchresults">Split fetchResults</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="AdvancedCollisionDetection.html">Advanced Collision Detection</a><ul> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#tuning-shape-collision-behavior">Tuning Shape Collision Behavior</a></li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#contact-modification">Contact Modification</a></li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#contact-reporting">Contact reporting</a><ul> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#contact-reports-and-ccd">Contact Reports and CCD</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#extracting-contact-information">Extracting Contact information</a><ul> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#extra-contact-data">Extra Contact Data</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#continuous-collision-detection">Continuous Collision Detection</a><ul> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#contact-notification-and-modification">Contact Notification and Modification</a></li> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#triggers">Triggers</a></li> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#tuning-ccd">Tuning CCD</a></li> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#performance-implications">Performance Implications</a></li> +<li class="toctree-l3"><a class="reference internal" href="AdvancedCollisionDetection.html#limitations">Limitations</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#raycast-ccd">Raycast CCD</a></li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#speculative-ccd">Speculative CCD</a></li> +<li class="toctree-l2"><a class="reference internal" href="AdvancedCollisionDetection.html#persistent-contact-manifold-pcm">Persistent Contact Manifold (PCM)</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Joints.html">Joints</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#joint-basics">Joint Basics</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#visualization">Visualization</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#force-reporting">Force Reporting</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#breakage">Breakage</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#projection">Projection</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#limits">Limits</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#actuation">Actuation</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#mass-scaling">Mass Scaling</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#fixed-joint">Fixed Joint</a></li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#spherical-joint">Spherical Joint</a></li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#revolute-joint">Revolute Joint</a></li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#prismatic-joint">Prismatic Joint</a></li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#distance-joint">Distance Joint</a></li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#d6-joint">D6 Joint</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#locking-and-unlocking-axes">Locking and Unlocking Axes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#id2">Limits</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#drives">Drives</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#configuring-joints-for-best-behavior">Configuring Joints for Best Behavior</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Joints.html#custom-constraints">Custom Constraints</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#defining-constraint-behavior">Defining Constraint Behavior</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#the-constraint-shader-table">The Constraint Shader Table</a></li> +<li class="toctree-l3"><a class="reference internal" href="Joints.html#data-management">Data Management</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Articulations.html">Articulations</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Articulations.html#creating-an-articulation">Creating an Articulation</a></li> +<li class="toctree-l2"><a class="reference internal" href="Articulations.html#articulation-joints">Articulation Joints</a></li> +<li class="toctree-l2"><a class="reference internal" href="Articulations.html#driving-an-articulation">Driving an Articulation</a></li> +<li class="toctree-l2"><a class="reference internal" href="Articulations.html#articulation-projection">Articulation Projection</a></li> +<li class="toctree-l2"><a class="reference internal" href="Articulations.html#articulations-and-sleeping">Articulations and Sleeping</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="OriginShift.html">Scene Origin</a><ul> +<li class="toctree-l2"><a class="reference internal" href="OriginShift.html#shifting-the-scene-origin">Shifting The Scene Origin</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="GPURigidBodies.html">GPU Rigid Bodies</a><ul> +<li class="toctree-l2"><a class="reference internal" href="GPURigidBodies.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="GPURigidBodies.html#using-gpu-rigid-bodies">Using GPU Rigid Bodies</a></li> +<li class="toctree-l2"><a class="reference internal" href="GPURigidBodies.html#what-is-gpu-accelerated">What is GPU accelerated?</a></li> +<li class="toctree-l2"><a class="reference internal" href="GPURigidBodies.html#tuning">Tuning</a></li> +<li class="toctree-l2"><a class="reference internal" href="GPURigidBodies.html#performance-considerations">Performance Considerations</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="GeometryQueries.html">Geometry Queries</a><ul> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#raycasts">Raycasts</a><ul> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#raycasts-against-spheres-capsules-boxes-and-convex-meshes">Raycasts against Spheres, Capsules, Boxes and Convex Meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#raycasts-against-planes">Raycasts against Planes</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#raycasts-against-triangle-meshes">Raycasts against Triangle Meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#raycasts-against-heightfields">Raycasts against Heightfields</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#overlaps">Overlaps</a></li> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#penetration-depth">Penetration Depth</a></li> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#sweeps">Sweeps</a><ul> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#initial-overlaps">Initial Overlaps</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#precise-sweeps">Precise Sweeps</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#sweeps-against-height-fields">Sweeps against Height Fields</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#pitfalls">Pitfalls</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#additional-pxgeometryquery-functions">Additional PxGeometryQuery functions</a></li> +<li class="toctree-l2"><a class="reference internal" href="GeometryQueries.html#pxmeshquery">PxMeshQuery</a><ul> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#mesh-overlaps">Mesh Overlaps</a></li> +<li class="toctree-l3"><a class="reference internal" href="GeometryQueries.html#sweeps-against-triangles">Sweeps against Triangles</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="SpatialQueries.html">Spatial Queries</a><ul> +<li class="toctree-l2"><a class="reference internal" href="SpatialQueries.html#pxspatialindex">PxSpatialIndex</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="SceneQueries.html">Scene Queries</a><ul> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#basic-queries">Basic queries</a><ul> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#raycasts">Raycasts</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#sweeps">Sweeps</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#overlaps">Overlaps</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#touching-and-blocking-hits">Touching and blocking hits</a></li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#query-modes">Query modes</a><ul> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#closest-hit">Closest hit</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#any-hit">Any hit</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#multiple-hits">Multiple hits</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#multiple-hits-with-blocking-hit">Multiple hits with blocking hit</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#filtering">Filtering</a><ul> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxqueryflag-estatic-pxqueryflag-edynamic">PxQueryFlag::eSTATIC, PxQueryFlag::eDYNAMIC</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxqueryflag-eprefilter-pxqueryflag-epostfilter">PxQueryFlag::ePREFILTER, PxQueryFlag::ePOSTFILTER</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxqueryflag-eany-hit">PxQueryFlag::eANY_HIT</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxqueryflag-eno-block">PxQueryFlag::eNO_BLOCK</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxfilterdata-fixed-function-filtering">PxFilterData fixed function filtering</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#user-defined-hit-callbacks-for-unbounded-results">User defined hit callbacks for unbounded results</a></li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#batched-queries">Batched queries</a></li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#volume-caching">Volume Caching</a><ul> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#filling-the-cache">Filling the Cache</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#querying-the-cache">Querying the Cache</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#single-object-caching">Single Object Caching</a></li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#pxpruningstructuretype">PxPruningStructureType</a><ul> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#generalities">Generalities</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxpruningstructuretype-enone">PxPruningStructureType::eNONE</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxpruningstructuretype-estatic-aabb-tree">PxPruningStructureType::eSTATIC_AABB_TREE</a></li> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#pxpruningstructuretype-edynamic-aabb-tree">PxPruningStructureType::eDYNAMIC_AABB_TREE</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="SceneQueries.html#pxpruningstructure">PxPruningStructure</a><ul> +<li class="toctree-l3"><a class="reference internal" href="SceneQueries.html#merge-process">Merge process</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Vehicles.html">Vehicles</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#algorithm">Algorithm</a></li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#first-code">First Code</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-sdk-initialization">Vehicle SDK Initialization</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#introduction-to-vehicle-creation">Introduction To Vehicle Creation</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#introduction-to-vehicle-update">Introduction To Vehicle Update</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#snippets">Snippets</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#snippetvehicle4w">SnippetVehicle4W</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#snippetvehicletank">SnippetVehicleTank</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#snippetvehiclenodrive">SnippetVehicleNoDrive</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#snippetvehiclescale">SnippetVehicleScale</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#snippetvehiclemultithreading">SnippetVehicleMultiThreading</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#advanced-concepts">Advanced Concepts</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-creation">Vehicle Creation</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#filtering">Filtering</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#tire-friction-on-drivable-surfaces">Tire Friction on Drivable Surfaces</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-controls">Vehicle Controls</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-update">Vehicle Update</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#more-advanced-concepts">More Advanced Concepts</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-telemetry">Vehicle Telemetry</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-update-multi-threaded">Vehicle Update Multi-Threaded</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#tire-shaders">Tire Shaders</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#vehicle-types">Vehicle Types</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#si-units">SI Units</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#level-of-detail">Level of Detail</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#wheel-contact-beyond-raycasts">Wheel Contact Beyond Raycasts</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#tuning-guide">Tuning Guide</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehiclewheeldata">PxVehicleWheelData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehiclewheelssimdata">PxVehicleWheelsSimData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehiclesuspensiondata">PxVehicleSuspensionData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicleantirollbar">PxVehicleAntiRollBar</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicletiredata">PxVehicleTireData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicleenginedata">PxVehicleEngineData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehiclegearsdata">PxVehicleGearsData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicleautoboxdata">PxVehicleAutoBoxData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicleclutchdata">PxVehicleClutchData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicleackermanngeometrydata">PxVehicleAckermannGeometryData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicletireloadfilterdata">PxVehicleTireLoadFilterData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxvehicledifferential4wdata">PxVehicleDifferential4WData</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#pxrigiddynamic">PxRigidDynamic</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#troubleshooting">Troubleshooting</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#jittery-vehicles">Jittery Vehicles</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-engine-rotation-refuses-to-spin-quickly">The Engine Rotation Refuses To Spin Quickly</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-engine-spins-but-the-wheels-refuse-to-spin">The Engine Spins But the Wheels Refuse To Spin</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-wheels-are-spinning-but-the-vehicle-does-not-move-forwards">The Wheels Are Spinning But The Vehicle Does Not Move Forwards</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-does-not-steer-turn">The Vehicle Does Not Steer/Turn</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-acceleration-feels-sluggish">The Acceleration Feels Sluggish</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-does-not-slow-down-when-not-accelerating">The Vehicle Does Not Slow Down When Not Accelerating</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-turns-too-quickly-too-slowly">The Vehicle Turns Too Quickly/Too Slowly</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-wheels-spin-too-much-under-acceleration">The Wheels Spin Too Much Under Acceleration</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-wheels-spin-too-much-when-cornering">The Wheels Spin Too Much When Cornering</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-never-goes-beyond-first-gear">The Vehicle Never Goes Beyond First Gear</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-under-steers-then-over-steers">The Vehicle Under-steers Then Over-steers</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-slows-down-unnaturally">The Vehicle Slows Down Unnaturally</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#the-vehicle-climbs-too-steep-slopes">The Vehicle Climbs Too Steep Slopes</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Vehicles.html#references">References</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#anti-roll-bar">Anti-roll Bar</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#tire-modeling">Tire Modeling</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#engine-torque-curves">Engine Torque Curves</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#differentials">Differentials</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#clutch">Clutch</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#ackermann-steer-correction">Ackermann Steer Correction</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#tanks">Tanks</a></li> +<li class="toctree-l3"><a class="reference internal" href="Vehicles.html#general">General</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="CharacterControllers.html">Character Controllers</a><ul> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#kinematic-character-controller">Kinematic Character Controller</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#creating-a-character-controller">Creating a character controller</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#overlap-recovery-module">Overlap Recovery Module</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#character-volume">Character Volume</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#volume-update">Volume Update</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#moving-a-character-controller">Moving a Character Controller</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#graphics-update">Graphics Update</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#auto-stepping">Auto Stepping</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#climbing-mode">Climbing Mode</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#up-vector">Up Vector</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#walkable-parts-invisible-walls">Walkable Parts & Invisible Walls</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#obstacle-objects">Obstacle Objects</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#hit-callback">Hit Callback</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#behavior-callback">Behavior Callback</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#character-interactions-cct-vs-dynamic-actors">Character Interactions: CCT-vs-dynamic actors</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#character-interactions-cct-vs-cct">Character Interactions: CCT-vs-CCT</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#hidden-kinematic-actors">Hidden Kinematic Actors</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#time-stepping">Time Stepping</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#invalidating-internal-geometry-caches">Invalidating Internal Geometry Caches</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#runtime-tessellation">Runtime Tessellation</a></li> +<li class="toctree-l2"><a class="reference internal" href="CharacterControllers.html#troubleshooting">Troubleshooting</a><ul> +<li class="toctree-l3"><a class="reference internal" href="CharacterControllers.html#character-goes-through-walls-in-rare-cases">Character goes through walls in rare cases</a></li> +<li class="toctree-l3"><a class="reference internal" href="CharacterControllers.html#tessellation-performance-issue">Tessellation performance issue</a></li> +<li class="toctree-l3"><a class="reference internal" href="CharacterControllers.html#the-capsule-controller-manages-to-climb-over-obstacles-higher-than-the-step-offset-value">The capsule controller manages to climb over obstacles higher than the step offset value</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Particles.html">Particles (deprecated)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#creating-particle-systems">Creating Particle Systems</a></li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#particle-management">Particle Management</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#creating-particles">Creating Particles</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#releasing-particles">Releasing Particles</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#index-pool-extension">Index Pool Extension</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#updating-particles">Updating Particles</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#reading-particles">Reading Particles</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#parameter-guide">Parameter Guide</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#particle-dynamics">Particle Dynamics</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#collision-with-rigid-actors">Collision with Rigid Actors</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#fluid-pxparticlefluid">Fluid (PxParticleFluid)</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#collision-handling">Collision Handling</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#collision-filtering">Collision Filtering</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#per-particle-rest-offsets">Per-particle Rest Offsets</a></li> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#particle-drains">Particle Drains</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#best-practices-troubleshooting">Best Practices / Troubleshooting</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Particles.html#particle-grid-and-spatial-data-structure-overflow">Particle Grid and Spatial Data Structure Overflow</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#gpu-cuda-acceleration">GPU/CUDA Acceleration</a></li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#sample-discussion">Sample Discussion</a></li> +<li class="toctree-l2"><a class="reference internal" href="Particles.html#references">References</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Cloth.html">Cloth</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Cloth.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Cloth.html#simulation-algorithm">Simulation Algorithm</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#solver-frequency">Solver Frequency</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#particle-integration">Particle Integration</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#local-space-simulation-and-inertia-scale">Local Space Simulation and Inertia Scale</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#constraints">Constraints</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#distance-constraints">Distance Constraints</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#tether-constraints">Tether Constraints</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#motion-constraints">Motion Constraints</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#separation-constraints">Separation Constraints</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#collision-detection">Collision Detection</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#continuous-collision-detection">Continuous Collision Detection</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#virtual-particle-collision">Virtual Particle Collision</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#friction-and-mass-scaling">Friction and Mass Scaling</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#self-collision-of-a-single-cloth-actor">Self-Collision of a Single Cloth Actor</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#inter-collision-between-multiple-cloth-actors">Inter-Collision between Multiple Cloth Actors</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Cloth.html#best-practices-troubleshooting">Best Practices / Troubleshooting</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#performance-tips">Performance Tips</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#using-gpu-cloth">Using GPU Cloth</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#fast-moving-characters">Fast-Moving Characters</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#avoiding-stretching">Avoiding Stretching</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#avoiding-jitter">Avoiding Jitter</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#pvd-support">PVD Support</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Cloth.html#snippet-discussion">Snippet Discussion</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#filling-in-pxclothmeshdesc">Filling in PxClothMeshDesc</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#creating-fabric">Creating Fabric</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#creating-cloth">Creating Cloth</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#specifying-collision-shapes">Specifying Collision Shapes</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#adding-virtual-particles">Adding Virtual Particles</a></li> +<li class="toctree-l3"><a class="reference internal" href="Cloth.html#accessing-particle-data">Accessing Particle Data</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Cloth.html#references">References</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="DebugVisualization.html">Debug Visualization</a><ul> +<li class="toctree-l2"><a class="reference internal" href="DebugVisualization.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="DebugVisualization.html#usage">Usage</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="VisualDebugger.html">PhysX Visual Debugger (PVD)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="VisualDebugger.html#pvd">PVD</a></li> +<li class="toctree-l2"><a class="reference internal" href="VisualDebugger.html#basic-setup-sdk-side">Basic Setup (SDK Side)</a><ul> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#network-setup">Network Setup</a></li> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#file-setup">File Setup</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="VisualDebugger.html#advanced-setup">Advanced Setup</a><ul> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#connection-flags">Connection Flags</a></li> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#visualizing-externals-and-extended-data">Visualizing Externals and Extended Data</a></li> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#visualizing-scenequery">Visualizing SceneQuery</a></li> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#custom-pvdclient">Custom PvdClient</a></li> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#pvd-error-stream">PVD Error Stream</a></li> +<li class="toctree-l3"><a class="reference internal" href="VisualDebugger.html#custom-profiling">Custom profiling</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Statistics.html">Simulation Statistics</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Statistics.html#interface">Interface</a></li> +<li class="toctree-l2"><a class="reference internal" href="Statistics.html#usage">Usage</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="Serialization.html">Serialization</a><ul> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#first-code">First Code</a></li> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#in-depth-discussion">In-depth Discussion</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#collections">Collections</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#serializing-complete-collections">Serializing Complete Collections</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#serializing-incomplete-collections">Serializing Incomplete Collections</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#reference-counting-of-deserialized-objects">Reference Counting of Deserialized Objects</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#reconnecting-physx-and-game-objects">Reconnecting PhysX and Game-Objects</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#serializing-everything">Serializing Everything</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#serializability">Serializability</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#binary-serialization-specifics">Binary Serialization Specifics</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#api-level-serialization-repx-specifics">API-level Serialization (RepX) Specifics</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#common-use-cases">Common Use Cases</a></li> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#snippet-discussion">Snippet Discussion</a><ul> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#snippetserialization">SnippetSerialization</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#snippetconvert">SnippetConvert</a></li> +<li class="toctree-l3"><a class="reference internal" href="Serialization.html#snippetloadcollection">SnippetLoadCollection</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#best-practices-troubleshooting">Best practices / Troubleshooting</a></li> +<li class="toctree-l2"><a class="reference internal" href="Serialization.html#pvd">PVD</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="ExtendingSerialization.html">Extending Serialization</a><ul> +<li class="toctree-l2"><a class="reference internal" href="ExtendingSerialization.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="ExtendingSerialization.html#overview">Overview</a></li> +<li class="toctree-l2"><a class="reference internal" href="ExtendingSerialization.html#binary-serialization-of-custom-classes">Binary Serialization of Custom Classes</a></li> +<li class="toctree-l2"><a class="reference internal" href="ExtendingSerialization.html#repx-serialization-of-custom-classes">RepX Serialization of Custom Classes</a><ul> +<li class="toctree-l3"><a class="reference internal" href="ExtendingSerialization.html#physx-api-metadata-system">PhysX API Metadata System</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="BestPractices.html">Best Practices Guide</a><ul> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#debugging">Debugging</a><ul> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-checked-builds-and-the-error-stream">Use checked builds and the error stream</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#visualizing-physics-data">Visualizing physics data</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#visualizing-physics-data-2">Visualizing physics data (2)</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#limiting-coordinates">Limiting coordinates</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#performance-issues">Performance Issues</a><ul> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-profile-builds-to-identify-performance-bottlenecks">Use profile builds to identify performance bottlenecks</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-release-builds-for-final-performance-tests">Use release builds for final performance tests</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#disable-debug-visualization-in-final-release-builds">Disable debug visualization in final/release builds</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#debug-visualization-is-very-slow">Debug visualization is very slow</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#consider-using-tight-bounds-for-convex-meshes">Consider using tight bounds for convex meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-scratch-buffers">Use scratch buffers</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-the-proper-mid-phase-algorithm">Use the proper mid-phase algorithm</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-the-proper-narrow-phase-algorithm">Use the proper narrow-phase algorithm</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-the-proper-broad-phase-algorithm">Use the proper broad-phase algorithm</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-the-scene-query-and-simulation-flags">Use the scene-query and simulation flags</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#tweak-the-dynamic-tree-rebuild-rate">Tweak the dynamic tree rebuild rate</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-the-insertion-callback-when-cooking-at-runtime">Use the insertion callback when cooking at runtime</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#the-well-of-despair">The "Well of Despair"</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#pruner-performance-for-streamed-environments">Pruner Performance for Streamed Environments</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#performance-implications-for-multi-threading">Performance Implications for Multi-Threading</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#memory-allocation">Memory allocation</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#character-controller-systems-using-scene-queries-and-penetration-depth-computation">Character Controller Systems using Scene Queries and Penetration Depth Computation</a></li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#quantizing-heightfield-samples">Quantizing HeightField Samples</a></li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#reducing-memory-usage">Reducing memory usage</a><ul> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#id1">Consider using tight bounds for convex meshes</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#id2">Use scratch buffers</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#flush-simulation-buffers">Flush simulation buffers</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#use-preallocation">Use preallocation</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#tweak-cooking-parameters">Tweak cooking parameters</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#share-shape-and-mesh-data">Share shape and mesh data</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#id3">Use the scene-query and simulation flags</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#behavior-issues">Behavior issues</a><ul> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#objects-do-not-spin-realistically">Objects do not spin realistically</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#overlapping-objects-explode">Overlapping objects explode</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#rigid-bodies-are-jittering-on-the-ground">Rigid bodies are jittering on the ground</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#piles-or-stacks-of-objects-are-not-going-to-sleep">Piles or stacks of objects are not going to sleep</a></li> +<li class="toctree-l3"><a class="reference internal" href="BestPractices.html#jointed-objects-are-unstable">Jointed objects are unstable</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#gpu-rigid-bodies">GPU Rigid Bodies</a></li> +<li class="toctree-l2"><a class="reference internal" href="BestPractices.html#determinism">Determinism</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="MigrationFrom28.html">Migrating From PhysX SDK 2.x to 3.x</a><ul> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#removed-features">Removed Features</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#compartments">Compartments</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#deformables">Deformables</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#nxutillib">NxUtilLib</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#anisotropic-friction">Anisotropic Friction</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#basics">Basics</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#sdk-header">SDK Header</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#sdk-redistribution">SDK Redistribution</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#api-conventions">API Conventions</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#callback-classes">Callback Classes</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#memory-management">Memory Management</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#debug-rendering">Debug Rendering</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#error-reporting">Error Reporting</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#type-casting">Type Casting</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#multithreading">Multithreading</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#startup-and-shutdown">Startup and Shutdown</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#extensions">Extensions</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#heightfields">Heightfields</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#cooking">Cooking</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#serialization">Serialization</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#api-design-changes">API Design Changes</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#changed-actor-hierarchy">Changed Actor Hierarchy</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#actor-creation">Actor Creation</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#material-indexes">Material Indexes</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#continuous-collision-detection">Continuous Collision Detection</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#pose-description">Pose Description</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#shape-description">Shape Description</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#skin-width">Skin Width</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#joints">Joints</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#time-stepping">Time Stepping</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#simulation-parameters">Simulation Parameters</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#collision-filtering">Collision Filtering</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationFrom28.html#scene-queries">Scene Queries</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#raycasts">Raycasts</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#overlaps">Overlaps</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationFrom28.html#sweep-tests">Sweep Tests</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="MigrationTo33.html">Migrating From PhysX SDK 3.2 to 3.3</a><ul> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#math-classes">Math Classes</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#scene-query-api">Scene Query API</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#spu-batch-queries">SPU batch queries</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#core-physx">Core PhysX</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#physx-extensions">PhysX Extensions</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#physx-character-controller">PhysX Character Controller</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#physx-vehicles">PhysX Vehicles</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#ccd">CCD</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#physx-visual-debugger">PhysX Visual Debugger</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#physx-cloth">PhysX Cloth</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#repx-serialization">RepX Serialization</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#binary-serialization">Binary Serialization</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo33.html#physx-taskmanager">PhysX TaskManager</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="MigrationTo34.html">Migrating From PhysX SDK 3.3 to 3.4</a><ul> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#deprecated-apis">Deprecated APIs</a><ul> +<li class="toctree-l3"><a class="reference internal" href="MigrationTo34.html#pxrigidactor-createshape">PxRigidActor::createShape</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationTo34.html#pxsceneflag-edeprecated-trigger-trigger-reports">PxSceneFlag::eDEPRECATED_TRIGGER_TRIGGER_REPORTS</a></li> +<li class="toctree-l3"><a class="reference internal" href="MigrationTo34.html#physx-particles">PhysX particles</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#core-physx">Core PhysX</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#contact-generation">Contact Generation</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#physx-cooking">PhysX Cooking</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#reference-counting">Reference Counting</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#physx-visual-debugger">PhysX Visual Debugger</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#scene-queries">Scene queries</a></li> +<li class="toctree-l2"><a class="reference internal" href="MigrationTo34.html#pxextensions">PxExtensions</a></li> +</ul> +</li> +</ul> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="../Index.html" + title="previous chapter">NVIDIA® PhysX® SDK 3.4.0 Documentation</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Introduction.html" + title="next chapter">Welcome to PhysX</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" /> + <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="Introduction.html" title="Welcome to PhysX" + >next</a></li> + <li class="right" > + <a href="../Index.html" title="NVIDIA® PhysX® SDK 3.4.0 Documentation" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Introduction.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Introduction.html new file mode 100644 index 00000000..328ef295 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Introduction.html @@ -0,0 +1,172 @@ +<!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>Welcome to PhysX — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Snippets" href="HelloWorld.html" /> + <link rel="prev" title="User's Guide" href="Index.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="HelloWorld.html" title="Snippets" + accesskey="N">next</a></li> + <li class="right" > + <a href="Index.html" title="User's Guide" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <span class="target" id="introduction"></span><div class="section" id="welcome-to-physx"> +<h1>Welcome to PhysX<a class="headerlink" href="#welcome-to-physx" title="Permalink to this headline">¶</a></h1> +<p>Welcome to the NVIDIA® PhysX® SDK version 3! With this second major rewrite of the SDK, we are excited to bring you a great number of enhancements, including numerous API improvements. Because so much has changed in the API, we recommend even experienced PhysX users to read through this guide to familiarize themselves with the new programming interface.</p> +<div class="section" id="about-this-user-guide"> +<h2>About this User Guide<a class="headerlink" href="#about-this-user-guide" title="Permalink to this headline">¶</a></h2> +<p>This Guide will help the reader to understand the PhysX-3 SDK and its applications. The Guide presents an overview of the +features and implementation of the PhysX SDK, and its performance in general use as well as in specific cases.</p> +<dl class="docutils"> +<dt>That is, this Guide covers:</dt> +<dd><ul class="first last simple"> +<li>what PhysX does;</li> +<li>how PhysX works;</li> +<li>how well PhysX is expected to perform;</li> +<li>how to use PhysX by example, and performance in those use cases.</li> +</ul> +</dd> +</dl> +<p>The Guide does not attempt to explain the details of the API, and the interested reader should refer to the PhysX API +Reference Documentation. ( See PhysXAPI.chm, in the Documentation directory under the main directory where the PhysX +SDK distro was unpacked.) Users migrating from PhysX-2 will find the <a class="reference internal" href="MigrationFrom28.html#migration"><em>Migrating From PhysX SDK 2.x to 3.x</em></a> chapter of particular interest.</p> +</div> +<div class="section" id="physics-vs-physx"> +<h2>Physics vs. PhysX<a class="headerlink" href="#physics-vs-physx" title="Permalink to this headline">¶</a></h2> +<p>Physics is a rich and broad scientific pursuit, an attempt to explain with mathematics the behavior of all matter, everything in the entire universe, +using concepts such as space, time, energy, inertia, momentum and force. In physics, space is assumed to extend infinitely in three dimensions, and +can be divided into infinitely small units with arbitrarily fine precision. In other words, positions in physics space are described by vectors of +real numbers in a 3-dimensional Cartesian coordinate system. In contrast, positions in PhysX simulation space are vectors of +single-precision floating point numbers.</p> +<p>Like the dimensions of space, time in physics is described by a real number, an infinite duration divisible into arbitrarily small intervals. Physics promises that if +the forces imposed on a system are known throughout some period of time, and if the state of the system is known precisely at some instant of time in that period, +then the state of the system can be determined precisely for any other instant throughout the time period. For example, if one observes a ball falling towards the +ground, and measures its position and velocity, one can calculate what the position and velocity of the ball must have been at an earlier time, as well as what they +must become at a later time. In contrast, time in a PhysX simulation is discrete, not continuous, and it runs only 'forwards'. That is, the state of the simulated +system is known only at specific instants in time, usually referred to as 'steps', and the simulation may only step forwards in time, never backwards. The state of +a PhysX system in between time steps is not precisely determined.</p> +<p>Because of such approximations a PhysX simulation is subject to limitations that are not seen in ordinary physics, and later sections in this +Guide will highlight these limitations wherever they are likely to concern the user. PhysX is best suited for quasi-real time interactive 3D applications where +performance and scalability are more important than precision. Here "quasi-real time" means that advancing a PhysX simulation by a given time step, +say 1/60 second, will take less than that amount of time on an observer's clock if the performance of the hardware platform is sufficient for the complexity of +the simulation. That the PhysX SDK is more widely used in computer and video games than in scientific or engineering applications is both a cause and an effect of +these design choices. Consequently this Guide usually refers to PhysX in the context of games, e.g. 'the game world', 'rigid body game objects', 'the character', etc.</p> +</div> +<div class="section" id="world-and-objects"> +<h2>World and Objects<a class="headerlink" href="#world-and-objects" title="Permalink to this headline">¶</a></h2> +<dl class="docutils"> +<dt>The basic concepts of the world within a PhysX simulation are easy to visualize:</dt> +<dd><ul class="first last simple"> +<li>The PhysX world comprises a collection of Scenes, each containing objects called Actors;</li> +<li>Each Scene defines its own reference frame encompassing all of space and time;</li> +<li>Actors in different Scenes do not interact with each other;</li> +<li>The three major types of Actors are rigid bodies, particles and cloth;</li> +<li>Characters and vehicles are complex specialized objects made from Actors;</li> +<li>Actors have physical state : position and orientation; velocity or momentum; energy; etc,</li> +<li>Actor physical state may evolve over time due to applied forces, constraints such as joints or contacts, and interactions between Actors.</li> +</ul> +</dd> +</dl> +<p>Games are a very visual medium and audible and games usually place very particular requirements on their graphics and sound. Production quality graphics and audio are +outside the scope of PhysX, but it is enormously valuable to be able to visualize this otherwise hidden world. Some of our example programs come with rudimentary built-in +visualization, and we also provide a stand-alone debugging tool called PhysX Visual Debugger (PVD). PVD provides a graphical view of the PhysX scene together with various +tools to inspect and visualize variables of every PhysX object. Additionally it can also record and visualize memory and timing data. See <a class="reference internal" href="VisualDebugger.html#physxvisualdebugger"><em>PhysX Visual Debugger (PVD)</em></a> for details.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Welcome to PhysX</a><ul> +<li><a class="reference internal" href="#about-this-user-guide">About this User Guide</a></li> +<li><a class="reference internal" href="#physics-vs-physx">Physics vs. PhysX</a></li> +<li><a class="reference internal" href="#world-and-objects">World and Objects</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Index.html" + title="previous chapter">User's Guide</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="HelloWorld.html" + title="next chapter">Snippets</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" /> + <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="HelloWorld.html" title="Snippets" + >next</a></li> + <li class="right" > + <a href="Index.html" title="User's Guide" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Joints.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Joints.html new file mode 100644 index 00000000..f694ae85 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Joints.html @@ -0,0 +1,678 @@ +<!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>Joints — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Articulations" href="Articulations.html" /> + <link rel="prev" title="Advanced Collision Detection" href="AdvancedCollisionDetection.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Articulations.html" title="Articulations" + accesskey="N">next</a></li> + <li class="right" > + <a href="AdvancedCollisionDetection.html" title="Advanced Collision Detection" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="joints"> +<span id="id1"></span><h1>Joints<a class="headerlink" href="#joints" title="Permalink to this headline">¶</a></h1> +<div class="section" id="joint-basics"> +<h2>Joint Basics<a class="headerlink" href="#joint-basics" title="Permalink to this headline">¶</a></h2> +<p>A joint constrains the way two actors move relative to one another. A typical use for a joint would be to model a door hinge or the shoulder of a character. Joints are implemented in the PhysX extensions library and cover many common scenarios, but if you have use cases that are not met by the joints packaged with PhysX, you can implement your own. Since joints are implemented as extensions, the pattern for creating them is slightly different from other PhysX objects.</p> +<p>Creation of simple joints and limits is demonstrated in the SnippetJoint snippet.</p> +<p>To create a joint, call the joint's creation function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRevoluteJointCreate</span><span class="p">(</span><span class="n">PxPhysics</span><span class="o">&</span> <span class="n">physics</span><span class="p">,</span> + <span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">actor0</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">localFrame0</span><span class="p">,</span> + <span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">actor1</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">localFrame1</span><span class="p">);</span> +</pre></div> +</div> +<p>This has the same pattern for all joints: two actors, and for each actor a constraint frame.</p> +<p>One of the actors must be movable, either a <em>PxRigidDynamic</em> or a <em>PxArticulationLink</em>. The other may be of one of those types, or a <em>PxRigidStatic</em>. Use a NULL pointer here to indicate an implicit actor representing the immovable global reference frame.</p> +<p>Each localFrame argument specifies a constraint frame relative to the actor's global pose. Each joint defines a relationship between the global positions and origins of the constraint frames that will be enforced by the PhysX constraint solver. In this example, the revolute joint constrains the origin points of the two frames to be coincident and their x-axes to coincide, but allows the two actors to rotate freely relative to one another around this common axis.</p> +<p>PhysX supports six different joint types:</p> +<ul class="simple"> +<li>a <strong>fixed</strong> joint locks the orientations and origins rigidly together</li> +<li>a <strong>distance</strong> joint keeps the origins within a certain distance range</li> +<li>a <strong>spherical</strong> joint (also called a <em>ball-and-socket</em>) keeps the origins together, but allows the orientations to vary freely.</li> +<li>a <strong>revolute</strong> joint (also called a <em>hinge</em>) keeps the origins and x-axes of the frames together, and allows free rotation around this common axis.</li> +<li>a <strong>prismatic</strong> joint (also called a <em>slider</em>) keeps the orientations identical, but allows the origin of each frame to slide freely along the common x-axis.</li> +<li>a <strong>D6</strong> joint is a highly configurable joint that allows specification of individual degrees of freedom either to move freely or be locked together. It can be used to implement a wide variety of mechanical and anatomical joints, but is somewhat less intuitive to configure than the other joint types. This joint is covered in detail below.</li> +</ul> +<p>All joints are implemented as plugins to the SDK through the PxConstraint class. A number of the properties for each joint are configured using the PxConstraintFlag enumeration.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">As in the rest of the PhysX API, all joint angles for limits and drive targets are specified in radians.</p> +</div> +<div class="section" id="visualization"> +<h3>Visualization<a class="headerlink" href="#visualization" title="Permalink to this headline">¶</a></h3> +<p>All standard PhysX joints support debug visualization. You can visualize the joint frames of each actor, and also any limits the joint may have.</p> +<p>By default, joints are not visualized. To visualize a joint, set its visualization constraint flag and the appropriate scene-level visualization parameters:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">setVisualizationParameter</span><span class="p">(</span><span class="n">PxVisualizationParameter</span><span class="o">::</span><span class="n">eJOINT_FRAMES</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">);</span> +<span class="n">scene</span><span class="o">-></span><span class="n">setVisualizationParameter</span><span class="p">(</span><span class="n">PxVisualizationParameter</span><span class="o">::</span><span class="n">eJOINT_LIMITS</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">);</span> + +<span class="p">...</span> + +<span class="n">joint</span><span class="o">-></span><span class="n">setConstraintFlag</span><span class="p">(</span><span class="n">PxConstraintFlag</span><span class="o">::</span><span class="n">eVISUALIZATION</span><span class="p">)</span> +</pre></div> +</div> +</div> +<div class="section" id="force-reporting"> +<h3>Force Reporting<a class="headerlink" href="#force-reporting" title="Permalink to this headline">¶</a></h3> +<p>The force applied at a joint may be retrieved after simulation with a call to getForce():</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">fetchResults</span><span class="p">(...)</span> +<span class="n">joint</span><span class="o">-></span><span class="n">getConstraint</span><span class="p">().</span><span class="n">getForce</span><span class="p">(</span><span class="n">force</span><span class="p">,</span> <span class="n">torque</span><span class="p">);</span> +</pre></div> +</div> +<p>The force is resolved at the origin of actor1's joint frame.</p> +<p>Note that this force is only updated while the joint's actors are awake.</p> +</div> +<div class="section" id="breakage"> +<h3>Breakage<a class="headerlink" href="#breakage" title="Permalink to this headline">¶</a></h3> +<p>All of the standard PhysX joints can be made <em>breakable</em>. A maximum breaking force and torque may be specified, and if the force or torque required to maintain the joint constraint exceeds this threshold, the joint will break. Breaking a joint generates a simulation event (see PxSimulationEventCallback::onJointBreak), and the joint no longer partakes in simulation, although it remains attached to its actors until it is deleted.</p> +<p>By default the threshold force and torque are set to FLT_MAX, making joints effectively unbreakable. To make a joint breakable, specify the force and torque thresholds.</p> +<p>joint->setBreakForce(100.0f, 100.0f);</p> +<p>A constraint flag records whether a joint is currently broken:</p> +<p>bool broken = (joint->getConstraintFlags() & PxConstraintFlag::eBROKEN) != 0;</p> +<p>Breaking a joint causes a callback via PxSimulationEventCallback::onConstraintBreak. In this callback, a pointer to the joint and its type are specified in the externalReference and type field of the PxConstraintInfo struct. If you have implemented your own joint types, use the PxConstraintInfo::type field to determine the dynamic type of the broken constraint. Otherwise, simply cast the externalReference to a PxJoint:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MySimulationEventCallback</span> +<span class="p">{</span> + <span class="kt">void</span> <span class="n">onConstraintBreak</span><span class="p">(</span><span class="n">PxConstraintInfo</span><span class="o">*</span> <span class="n">constraints</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">count</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">PxJoint</span><span class="o">*</span> <span class="n">joint</span> <span class="o">=</span> <span class="k">reinterpret_cast</span><span class="o"><</span><span class="n">PxJoint</span><span class="o">*></span><span class="p">(</span><span class="n">constraints</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">externalReference</span><span class="p">);</span> + <span class="p">...</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="projection"> +<h3>Projection<a class="headerlink" href="#projection" title="Permalink to this headline">¶</a></h3> +<p>Under stressful conditions, PhysX' dynamics solver may not be able to accurately enforce the constraints specified by the joint. PhysX provides kinematic <em>projection</em> which tries to bring violated constraints back into alignment even when the solver fails. Projection is not a physical process and does not preserve momentum or respect collision geometry. It is best avoided if practical, but can be useful in improving simulation quality where joint separation results in unacceptable artifacts.</p> +<p>By default projection is disabled. To enable projection, set the linear and angular tolerance values beyond which a joint will be projected, and set the constraint projection flag:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setProjectionLinearTolerance</span><span class="p">(</span><span class="mf">0.1f</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setConstraintFlag</span><span class="p">(</span><span class="n">PxConstraintFlag</span><span class="o">::</span><span class="n">ePROJECTION</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Very small tolerance values for projection may result in jittering around the joint.</p> +<p>A constraint with projection enabled can be part of a graph of rigid bodies connected by constraints. If this graph is acyclic, the algorithm will choose a root node among the connected rigid bodies, traverse the graph, and project the bodies towards the root. If the constraint graph has cycles, the algorithm will split the graph into multiple acyclic subgraphs, dropping edges that create cycles, and do the projection separately for each. Please note that having more than one constraint attached to a fixed anchor (world or static/kinematic rigid body) in a graph does count as a cycle (for example, a chain of rigid bodies connected with constraints and both ends attached to world anchors). +If multiple constraints fight over the same body or conflicting projection directions are specified, the projection direction will be chosen based on the following priorities (highest first):</p> +<ul class="simple"> +<li>world attachment or a rigid static actor with a projecting constraint</li> +<li>kinematic actor with a projecting constraint</li> +<li>all dominant dynamic actor (has projecting constraints and all of them are one-way projecting towards this dynamic)</li> +<li>dominant dynamic actor (same as above but there is at least one two-way projecting constraint as well)</li> +<li>partially dominant dynamic actor (has at least one one-way projecting constraint towards this dynamic and at least one one-way projecting constraint towards an other actor)</li> +<li>world attachment or a rigid static actor without any projecting constraints</li> +<li>kinematic actor without any projecting constraints</li> +<li>dynamic actor with or without two-way projecting constraints to other dynamics (among these, the one with the highest constraint count wins)</li> +</ul> +</div> +<div class="section" id="limits"> +<h3>Limits<a class="headerlink" href="#limits" title="Permalink to this headline">¶</a></h3> +<p>Some PhysX joints constrain not just relative rotation or translation, but can also enforce <em>limits</em> on the range of that motion. For example, in its initial configuration the revolute joint allows free rotation around its axis, but by specifying and enabling a limit, lower and upper bounds may be placed upon the angle of rotation.</p> +<p>Limits are a form of collision, and like collision of rigid body shapes, stable limit behavior requires a <em>contactDistance</em> tolerance specifying how far from the limit the joint configuration may be before the solver tries to enforce it. Note that enforcement always starts before the limit is violated, so the role played by contactDistance for limits is analogous to the role a positive contactDistance value plays in collision detection. A larger contact makes the limit less likely to be violated even at high relative velocity. However, because the limit is active more of the time, the joint is more expensive to simulate.</p> +<p>Limit configuration is specific to each type of joint. To set a limit, configure the limit geometry and set the joint-specific flag indicating that the limit is enabled:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">revolute</span><span class="o">-></span><span class="n">setLimit</span><span class="p">(</span><span class="n">PxJointAngularLimitPair</span><span class="p">(</span><span class="o">-</span><span class="n">PxPi</span><span class="o">/</span><span class="mi">4</span><span class="p">,</span> <span class="n">PxPi</span><span class="o">/</span><span class="mi">4</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">));</span> <span class="c1">// upper, lower, tolerance</span> +<span class="n">revolute</span><span class="o">-></span><span class="n">setRevoluteJointFlag</span><span class="p">(</span><span class="n">PxRevoluteJointFlag</span><span class="o">::</span><span class="n">eLIMIT_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Limits may be either <em>hard</em> or <em>soft</em>. When a hard limit is reached, relative motion will simply stop dead if the limit is configured with zero restitution, or bounce if the restitution is non-zero. When a soft limit is violated, the solver will pull the joint back towards the limit using a spring specified by the limit's spring and damping parameters. By default, limits are hard and without restitution, so when the joint reaches a limit motion will simply stop. To specify softness for a limit, declare the limit structure and set the spring and damping parameters directly:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxJointAngularLimitPair</span> <span class="nf">limitPair</span><span class="p">(</span><span class="o">-</span><span class="n">PxPi</span><span class="o">/</span><span class="mi">4</span><span class="p">,</span> <span class="n">PxPi</span><span class="o">/</span><span class="mi">4</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">));</span> +<span class="n">limitPair</span><span class="p">.</span><span class="n">spring</span> <span class="o">=</span> <span class="mf">100.0f</span><span class="p">;</span> +<span class="n">limitPair</span><span class="p">.</span><span class="n">damping</span> <span class="o">=</span> <span class="mf">20.0f</span><span class="p">;</span> +<span class="n">revolute</span><span class="o">-></span><span class="n">setRevoluteJointLimit</span><span class="p">(</span><span class="n">limitPair</span><span class="p">);</span> +<span class="n">revolute</span><span class="o">-></span><span class="n">setRevoluteJointFlag</span><span class="p">(</span><span class="n">PxRevoluteJointFlag</span><span class="o">::</span><span class="n">eLIMIT_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Limits are not projected.</p> +</div> +<p>When using spring limits, the eACCELERATION flag is strongly recommended. This flag will automatically scale the strength of the spring according to the masses and inertias of objects that the limit is acting upon, and can substantially reduce the amount of tuning required for good, stable behavior.</p> +</div> +<div class="section" id="actuation"> +<h3>Actuation<a class="headerlink" href="#actuation" title="Permalink to this headline">¶</a></h3> +<p>Some PhysX joints may be actuated by a motor or a spring implicitly integrated by the PhysX solver. While driving simulations with actuated joints is more expensive than simply applying forces, it can provide much more stable control of simulation. See <a class="reference internal" href="#pxd6joint"><em>D6 Joint</em></a>, <a class="reference internal" href="#pxprismaticjoint"><em>Prismatic Joint</em></a>, and <a class="reference internal" href="#pxrevolutejoint"><em>Revolute Joint</em></a> for details</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The force generated by actuation is not included in the force reported by the solver, nor does it contribute towards exceeding the joint's breakage force threshold.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Changing the drive parameters for a joint, or activating or deactivating the drive, does not wake sleeping bodies attached to the joint. If required, wake these bodies manually.</p> +</div> +<p>When using spring drives (in particular, drives on the D6 joint), the eACCELERATION flag is strongly recommended. This flag will automatically scale the strength of the spring according to the masses and inertias of objects that the limit is acting upon, and can substantially reduce the amount of tuning required for good, stable behavior.</p> +</div> +<div class="section" id="mass-scaling"> +<span id="joint-mass-scaling"></span><h3>Mass Scaling<a class="headerlink" href="#mass-scaling" title="Permalink to this headline">¶</a></h3> +<p>PhysX joints may apply scale to the mass and moment of inertia of the two connected bodies for the purposes of resolving a joint. For example, if you have two objects in a ragdoll of masses 1 and 10, PhysX will typically resolve the joint by changing the velocity of the lighter body much more than the heavier one. You can apply a mass scale of 10 to the first body to make PhysX change the velocity of both bodies by an equal amount. To ensure the same property holds for both linear and angular velocity, you should adjust the inertia scales in accordance with the bodies' inertias as well. Applying mass scales such that the joint sees similar effective masses and inertias makes the solver converge faster, which can make individual joints seem less rubbery or separated, and sets of jointed bodies appear less twitchy</p> +<p>Many applications that prioritize visual behavior over adherence to physical laws can benefit from tuning these scale values. But if you use this feature, bear in mind that mass and inertia scaling is fundamentally nonphysical. In general momentum will not be conserved, the energy of the system may increase, the force reported for the joint may be incorrect, and non-physical tuning of breakage thresholds and force limits may be required.</p> +</div> +</div> +<div class="section" id="fixed-joint"> +<h2>Fixed Joint<a class="headerlink" href="#fixed-joint" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/fixedJoint.png" src="../_images/fixedJoint.png" /> +<p>The fixed joint constrains two objects so that the positions and orientations of their constraint frames are the same.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">All joints are enforced by the dynamics solver, so although under ideal conditions the objects will maintain their spatial relationship, there may be some drift. A common alternative, which is cheaper to simulate and does not suffer from drift, is to construct a single actor with multiple shapes. However fixed joints are useful, for example, when a joint must be breakable or report its constraint force.</p> +</div> +</div> +<div class="section" id="spherical-joint"> +<h2>Spherical Joint<a class="headerlink" href="#spherical-joint" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/sphericalJoint.png" src="../_images/sphericalJoint.png" /> +<p>A spherical joint constrains the origins of the actor's constraint frames to be coincident.</p> +<p>The spherical joint supports a cone limit, which constrains the angle between the X-axes of the two constraint frames. Actor1's X-axis is constrained by a limit cone whose axis is the x-axis of actor0's constraint frame. The allowed limit values are the maximum rotation around the y- and z- axes of that frame. Different values for the y- and z- axes may be specified, in which case the limit takes the form of an elliptical angular cone:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setLimitCone</span><span class="p">(</span><span class="n">PxJointLimitCone</span><span class="p">(</span><span class="n">PxPi</span><span class="o">/</span><span class="mi">2</span><span class="p">,</span> <span class="n">PxPi</span><span class="o">/</span><span class="mi">6</span><span class="p">,</span> <span class="mf">0.01f</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setSphericalJointFlag</span><span class="p">(</span><span class="n">PxSphericalJointFlag</span><span class="o">::</span><span class="n">eLIMIT_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Note that very small or highly elliptical limit cones may result in solver jitter.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last"><em>Visualization of the limit surface can help considerably in understanding its shape.</em></p> +</div> +</div> +<div class="section" id="revolute-joint"> +<span id="pxrevolutejoint"></span><h2>Revolute Joint<a class="headerlink" href="#revolute-joint" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/revoluteJoint.png" src="../_images/revoluteJoint.png" /> +<p>A revolute joint removes all but a single rotational degree of freedom from two objects. The axis along which the two bodies may rotate is specified by the common origin of the joint frames and their common x-axis. In theory, all origin points along the axis of rotation are equivalent, but simulation stability is best in practice when the point is near where the bodies are closest.</p> +<p>The joint supports a rotational limit with upper and lower extents. The angle is zero where the y- and z- axes of the joint frames are coincident, and increases moving from the y-axis towards the z-axis:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setLimit</span><span class="p">(</span><span class="n">PxJointLimitPair</span><span class="p">(</span><span class="o">-</span><span class="n">PxPi</span><span class="o">/</span><span class="mi">4</span><span class="p">,</span> <span class="n">PxPi</span><span class="o">/</span><span class="mi">4</span><span class="p">,</span> <span class="mf">0.01f</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setRevoluteJointFlag</span><span class="p">(</span><span class="n">PxRevoluteJointFlag</span><span class="o">::</span><span class="n">eLIMIT_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>The joint also supports a motor which drives the relative angular velocity of the two actors towards a user-specified target velocity. The magnitude of the force applied by the motor may be limited to a specified maximum:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setDriveVelocity</span><span class="p">(</span><span class="mf">10.0f</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setRevoluteJointFlag</span><span class="p">(</span><span class="n">PxRevoluteJointFlag</span><span class="o">::</span><span class="n">eDRIVE_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>By default, when the angular velocity at the joint exceeds the target velocity the motor acts as a brake; a freespin flag disables this braking behavior.</p> +<p>The drive force limit for a revolute joint may be interpreted either as a force or an impulse, depending on the value of PxConstraintFlag::eDRIVE_LIMITS_ARE_FORCES</p> +</div> +<div class="section" id="prismatic-joint"> +<span id="pxprismaticjoint"></span><h2>Prismatic Joint<a class="headerlink" href="#prismatic-joint" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/prismJoint.png" src="../_images/prismJoint.png" /> +<p>A prismatic joint prevents all rotational motion, but allows the origin of actor1's constraint frame to move freely along the x-axis of actor0's constraint frame. The prismatic joint supports a single limit with upper and lower bounds on the distance between the two constraint frames' origin points:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setLimit</span><span class="p">(</span><span class="n">PxJointLimitPair</span><span class="p">(</span><span class="o">-</span><span class="mf">10.0f</span><span class="p">,</span> <span class="mf">20.0f</span><span class="p">,</span> <span class="mf">0.01f</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setPrismaticJointFlag</span><span class="p">(</span><span class="n">PxPrismaticJointFlag</span><span class="o">::</span><span class="n">eLIMIT_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="distance-joint"> +<h2>Distance Joint<a class="headerlink" href="#distance-joint" title="Permalink to this headline">¶</a></h2> +<img alt="../_images/distanceJoint.png" src="../_images/distanceJoint.png" /> +<p>The distance joint keeps the origins of the constraint frames within a certain range of distance. The range may have both upper and lower bounds, which are enabled separately by flags:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">joint</span><span class="o">-></span><span class="n">setMaxDistance</span><span class="p">(</span><span class="mf">10.0f</span><span class="p">);</span> +<span class="n">joint</span><span class="o">-></span><span class="n">setDistanceJointFlag</span><span class="p">(</span><span class="n">eMAX_DISTANCE_ENABLED</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>In addition, when the joint reaches the limits of its range motion beyond this distance may either be entirely prevented by the solver, or pushed back towards its range with an implicit spring, for which spring and damping parameters may be specified.</p> +</div> +<div class="section" id="d6-joint"> +<span id="pxd6joint"></span><h2>D6 Joint<a class="headerlink" href="#d6-joint" title="Permalink to this headline">¶</a></h2> +<p>The D6 joint is by far the most complex of the standard PhysX joints. In its default state it behaves like a fixed joint - that is, it rigidly fixes the constraint frames of its two actors. However, individual degrees of freedom may be unlocked to permit any combination of rotation around the x-, y- and z- axes, and translation along these axes.</p> +<div class="section" id="locking-and-unlocking-axes"> +<h3>Locking and Unlocking Axes<a class="headerlink" href="#locking-and-unlocking-axes" title="Permalink to this headline">¶</a></h3> +<p>To unlock and lock degrees of freedom, use the joint's setMotion function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eX</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +</pre></div> +</div> +<p>Unlocking translational degrees of freedom allows the origin point of actor1's constraint frame to move along a subset of the axes defined by actor0's constraint frame. For example, unlocking just the X-axis creates the equivalent of a prismatic joint.</p> +<p>Rotational degrees of freedom are partitioned as <em>twist</em> (around the X-axis of actor0's constraint frame) and <em>swing</em> (around the Y- and Z- axes). Different effects are achieved by unlocking various combinations of twist and swing.</p> +<ul class="simple"> +<li>if just a single degree of angular freedom is unlocked, the result is always equivalent to a revolute joint. It is recommended that if just one angular freedom is unlocked, it should be the twist degree, because the joint has various configuration options and optimizations that are designed for this case.</li> +</ul> +<ul class="simple"> +<li>if both swing degrees of freedom are unlocked but the twist degree remains locked, the result is a <em>zero-twist</em> joint. The x-axis of actor1 swings freely away from the x-axis of actor0 but twists to minimize the rotation required to align the two frames. This creates a kind of isotropic universal joint which avoids the problems of the usual 'engineering style' universal joint (see below) that is sometimes used as a kind of twist constraint. There is a nasty singularity at π radians (180 degrees) swing, so a swing limit should be used to avoid the singularity.</li> +</ul> +<ul class="simple"> +<li>if one swing and one twist degree of freedom are unlocked but the remaining swing is kept locked, a <em>zero-swing</em> joint results (often also called a <em>universal</em> joint). If for example the SWING1 (y-axis rotation) is unlocked, the x-axis of actor1 is constrained to remain orthogonal to the z-axis of actor0. In character applications, this joint can be used to model an elbow swing joint incorporating the twist freedom of the lower arm or a knee swing joint incorporating the twist freedom of the lower leg. In vehicle applications, these joints can be used as 'steered wheel' joints in which the child actor is the wheel, free to rotate about its twist axis, while the free swing axis in the parent acts as the steering axis. Care must be taken with this combination because of anisotropic behavior and singularities (beware the dreaded gimbal lock) at angles of π/2 radians (90 degrees), making the zero-twist joint a better behaved alternative for most use cases.</li> +</ul> +<ul class="simple"> +<li>if all three angular degrees are unlocked, the result is equivalent to a spherical joint.</li> +</ul> +<p>Three of the joints from PhysX 2 that have been removed from PhysX 3 can be implemented as follows:</p> +<ul> +<li><p class="first">The cylindrical joint (with axis along the common x-axis of the two constraint frames) is given by the combination:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eX</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eTWIST</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +</pre></div> +</div> +</li> +<li><p class="first">the point-on-plane joint (with plane axis along the x-axis of actor0's constraint frame) is given by the combination:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eY</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eZ</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eTWIST</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eSWING1</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eSWING2</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +</pre></div> +</div> +</li> +<li><p class="first">the point-on-line joint (with axis along the x-axis of actor0's constraint frame) is given by the combination:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eX</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eTWIST</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eSWING1</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eSWING2</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +</pre></div> +</div> +</li> +</ul> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Angular projection is implemented only for the cases when two or three angular degrees of freedom are locked.</p> +</div> +</div> +<div class="section" id="id2"> +<h3>Limits<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>Instead of specifying that an axis is free or locked, it may also be specified as limited. The D6 supports three different limits which may be used in any combination.</p> +<p>A single linear limit with only an upper bound is used to constrain any of the translational degrees of freedom. The limit constrains the distance between the origins of the constraint frames when projected onto these axes. For example, the combination:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eX</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eY</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eLIMITED</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eZ</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eLIMITED</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setLinearLimit</span><span class="p">(</span><span class="n">PxJointLinearLimit</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">));</span> +</pre></div> +</div> +<p>constrains the y- and z- coordinates of actor1's constraint frame to lie within the unit disc. Since the x-axis is unconstrained, the effect is to constrain the origin of actor1's constraint frame to lie within a cylinder of radius 1 extending along the x-axis of actor0's constraint frame.</p> +<p>The twist degree of freedom is limited by a pair limit with upper and lower bounds, identical to the limit of the revolute joint.</p> +<p>If both swing degrees of freedom are limited, a limit cone is generated, identical to the limit of the spherical joint. As with the spherical joint, very small or highly elliptical limit cones may result in solver jitter.</p> +<p>If only one swing degree of freedom is limited, the corresponding angle from the cone limit is used to limit rotation. If the other swing degree is locked, the maximum value of the limit is π radians (180 degrees). If the other swing degree is free, the maximum value of the limit is π/2 radians (90 degrees).</p> +</div> +<div class="section" id="drives"> +<h3>Drives<a class="headerlink" href="#drives" title="Permalink to this headline">¶</a></h3> +<p>The D6 has a linear drive model, and two possible angular drive models. The drive is a <em>proportional derivative</em> drive, which applies a force as follows:</p> +<p><em>force = spring * (targetPosition - position) + damping * (targetVelocity - velocity)</em></p> +<p>The drive model may also be configured to generate a proportional acceleration instead of a force, factoring in the masses of the actors to which the joint is attached. Acceleration drive is often easier to tune than force drive.</p> +<dl class="docutils"> +<dt>The linear drive model for the D6 has the following parameters:</dt> +<dd><ul class="first last simple"> +<li>target position, specified in actor0's constraint frame</li> +<li>target velocity, specified in actor0's constraint frame</li> +<li>spring</li> +<li>damping</li> +<li>forceLimit - the maximum force the drive can apply (note that this can be an impulse, depending on PxConstraintFlag::eDRIVE_LIMITS_ARE_FORCES)</li> +<li>acceleration drive flag</li> +</ul> +</dd> +</dl> +<p>The drive attempts to follow the desired position input with the configured stiffness and damping properties. A physical lag due to the inertia of the driven body acting through the drive spring will occur; therefore, sudden step changes will result over a number of time steps. Physical lag can be reduced by stiffening the spring or supplying a velocity target.</p> +<p>With a fixed position input and a zero target velocity, a position drive will spring about that drive position with the specified springing/damping characteristics:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// set all translational degrees free</span> + +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eX</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eY</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setMotion</span><span class="p">(</span><span class="n">PxD6Axis</span><span class="o">::</span><span class="n">eZ</span><span class="p">,</span> <span class="n">PxD6Motion</span><span class="o">::</span><span class="n">eFREE</span><span class="p">);</span> + +<span class="c1">// set all translation degrees driven:</span> + +<span class="n">PxD6Drive</span> <span class="nf">drive</span><span class="p">(</span><span class="mf">10.0f</span><span class="p">,</span> <span class="o">-</span><span class="mf">20.0f</span><span class="p">,</span> <span class="n">PX_MAX_F32</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setDrive</span><span class="p">(</span><span class="n">PxD6JointDrive</span><span class="o">::</span><span class="n">eX</span><span class="p">,</span> <span class="n">drive</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setDrive</span><span class="p">(</span><span class="n">PxD6JointDrive</span><span class="o">::</span><span class="n">eY</span><span class="p">,</span> <span class="n">drive</span><span class="p">);</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setDrive</span><span class="p">(</span><span class="n">PxD6JointDrive</span><span class="o">::</span><span class="n">eZ</span><span class="p">,</span> <span class="n">drive</span><span class="p">);</span> + +<span class="c1">// Drive the joint to the local(actor[0]) origin - since no angular</span> +<span class="c1">// dofs are free, the angular part of the transform is ignored</span> + +<span class="n">d6joint</span><span class="o">-></span><span class="n">setDrivePosition</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">));</span> +<span class="n">d6joint</span><span class="o">-></span><span class="n">setDriveVelocity</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="n">PxZero</span><span class="p">));</span> +</pre></div> +</div> +<p>Angular drive differs from linear drive in a fundamental way: it does not have a simple and intuitive representation free from singularities. For this reason, the D6 joint provides two angular drive models - twist and swing and SLERP (Spherical Linear Interpolation).</p> +<p>The two models differ in the way they estimate the path in quaternion space between the current orientation and the target orientation. In a SLERP drive, the quaternion is used directly. In a twist and swing drive, it is decomposed into separate twist and swing components and each component is interpolated separately. Twist and swing is intuitive in many situations; however, there is a singularity when driven to 180 degrees swing. In addition, the drive will not follow the shortest arc between two orientations. On the other hand, SLERP drive will follow the shortest arc between a pair of angular configurations, but may cause unintuitive changes in the joint's twist and swing.</p> +<p>The angular drive model has the following parameters:</p> +<blockquote> +<div><ul class="simple"> +<li>An angular velocity target specified relative to actor0's constraint frame</li> +<li>An orientation target specified relative to actor0's constraint frame</li> +<li>drive specifications for SLERP (slerpDrive), swing (swingDrive) and twist (twistDrive):</li> +<li>spring - amount of torque needed to move the joint to its target orientation proportional to the angle from the target (not used for a velocity drive).</li> +<li>damping - applied to the drive spring (used to smooth out oscillations about the drive target).</li> +<li>forceLimit - the maximum torque the drive can apply (note that this can be an impulsive torque, depending on the value PxConstraintFlag::eDRIVE_LIMITS_ARE_FORCES)</li> +<li>acceleration drive flag. If this flag is set the acceleration (rather than the force) applied by the drive is proportional to the angle from the target.</li> +</ul> +</div></blockquote> +<p>Best results will be achieved when the drive target inputs are consistent with the joint freedom and limit constraints.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">if any angular degrees of freedom are locked, the SLERP drive parameters are ignored. If all angular degrees of freedom are unlocked, and parameters are set for multiple angular drives, the SLERP parameters will be used.</p> +</div> +</div> +<div class="section" id="configuring-joints-for-best-behavior"> +<h3>Configuring Joints for Best Behavior<a class="headerlink" href="#configuring-joints-for-best-behavior" title="Permalink to this headline">¶</a></h3> +<p>The behavior quality of joints in PhysX is largely determined by the ability of the iterative solver to converge. Better convergence can be achieved simply by increasing the attributes of the PxRigidDynamic which controls the solver iteration count. However, joints can also be configured to produce better convergence.</p> +<ul class="simple"> +<li>the solver can have difficulty converging well when a light object is constrained between two heavy objects. Mass ratios of higher than 10 are best avoided in such scenarios.</li> +<li>when one body is significantly heavier than the other, make the lighter body the second actor in the joint. Similarly, when one of the objects is static or kinematic (or the actor pointer is NULL) make the dynamic body the second actor.</li> +</ul> +<p>A common use for joints is to move objects around in the world. Best results are obtained when the solver has access to the velocity of motion as well as the change in position.</p> +<ul class="simple"> +<li>if you want a very stiff controller that moves the object to specific position each frame, consider jointing the object to a kinematic actor and use the setKinematicTarget function to move the actor.</li> +<li>if you want a more springy controller, use a D6 joint with a drive target to set the desired position and orientation, and control the spring parameters to increase stiffness and damping. In general, acceleration drive is much easier to tune than force drive.</li> +</ul> +<p>When using mass scaling or when constraining bodies with infinite inertia along some axes, the reduction in degrees of freedom of the rigid bodies combined with small inaccuracies in floating point calculation can produce arbitrarily stiff constraint responses trying to correct unnoticeably small errors. This can appear, for example, when attempting to perform 2D-simulation using infinite inertia to suppress velocity out of the plane of simulation. In these cases, set the flag PxConstraintFlag::eDISABLE_PREPROCESSING, and set the minResponseThreshold on the constraint to a small value, e.g. 1e-8. This will result in such stiff constraint rows being ignored when encountered, and can considerably improve simulation quality.</p> +</div> +</div> +<div class="section" id="custom-constraints"> +<h2>Custom Constraints<a class="headerlink" href="#custom-constraints" title="Permalink to this headline">¶</a></h2> +<p>It is also possible to add new joint types to PhysX. Use the existing joints in the PhysXExtensions library as a reference, and also the source for SnippetCustomJoint, which shows how to implement a Pulley Joint. Serializing custom objects is discussed in the chapter <a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a>, so the discussion here is limited to how to achieve the desired behavior in simulation. This is an advanced topic, and assumes familiarity with the mathematics underlying rigid body simulation. The presentation here assumes that the joint constrains two bodies; the case for a static body is equivalent to a dynamic body of infinite mass whose transform is the identity.</p> +<p>The functions which implement dynamic behavior of joints are PhysX <em>shaders</em>, similar in nature to the PxFilterShader (see <a class="reference internal" href="RigidBodyCollision.html#collisionfiltering"><em>Collision Filtering</em></a>). In particular, the functions may execute in parallel and asynchronously, and should not access any state except that passed in as parameters.</p> +<p>To create a custom joint class, define the following:</p> +<ul class="simple"> +<li>the functions which implement the behavior of the constraint. The functions must be stateless, because they may be called simultaneously from multiple threads. When each function is called, PhysX passes a <em>constant block</em> which can be used to store the joint configuration parameters (offsets, axes, limits etc).</li> +<li>a static instance of PxConstraintShaderTable containing pointers to the functions</li> +<li>a class implementing the PxConstraintConnector interface, that connects the custom joint to PhysX.</li> +</ul> +<div class="section" id="defining-constraint-behavior"> +<h3>Defining Constraint Behavior<a class="headerlink" href="#defining-constraint-behavior" title="Permalink to this headline">¶</a></h3> +<p>There are two functions that define the joint behavior: the <em>solver preparation</em> function, which generates inputs to PhysX' velocity-based constraint solver, and the <em>projection</em> function, which allows direct correction of position error.</p> +<p>The processing sequence during simulation is as follows:</p> +<ul class="simple"> +<li>in the simulate() function, before starting simulation the scene updates an internal copy of the joint's constant block (so that the joint's copy may be modified during simulation without causing races).</li> +<li>collision detection runs, and may wake bodies. If the joint connects two bodies, the simulation will ensure that either both bodies are awake, or neither is.</li> +<li>for every joint connected to an awake body, the simulation calls the solver preparation function.</li> +<li>the solver updates body velocities and positions.</li> +<li>if the constraint's ePROJECTION flag is set, the simulation calls the joint projection function.</li> +</ul> +<div class="section" id="the-solver-preparation-function"> +<h4>The Solver Preparation Function<a class="headerlink" href="#the-solver-preparation-function" title="Permalink to this headline">¶</a></h4> +<p>The solver preparation function for a joint has the following signature:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="nf">prepare</span><span class="p">(</span><span class="n">Px1DConstraint</span><span class="o">*</span> <span class="n">constraints</span><span class="p">,</span> + <span class="n">PxVec3</span><span class="o">&</span> <span class="n">bodyAWorldOffset</span><span class="p">,</span> + <span class="n">PxU32</span> <span class="n">maxConstraints</span><span class="p">,</span> + <span class="n">PxConstraintInvMassScale</span> <span class="o">&</span><span class="n">invMassScale</span><span class="p">,</span> + <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">bA2w</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">bB2w</span><span class="p">);</span> +</pre></div> +</div> +<p>The parameters are as follows:</p> +<ul class="simple"> +<li><em>constraints</em> is the output buffer of constraint rows.</li> +<li><em>bodyAWorldOffset</em> is the point, specified in world space as an offset from the origin of bodyA, at which the constraint forces act to enforce the joint. The constraint solver ignores this value as the information is already encoded in the constraint array, but when reporting forces it is necessary to choose a point at which the force is considered to act. For PhysX joints, the attachment point of the joint on body B is used.</li> +<li><em>maxConstraints</em> is the size of the buffer, which limits the number of constraint rows that may be generated.</li> +<li><em>invMassScale</em> is the inverse mass scales which should be applied to the bodies for the purpose of resolving the joint. In the standard joints, these are just the joint's mass scaling parameters (see <a class="reference internal" href="#joint-mass-scaling"><em>Mass Scaling</em></a>).</li> +<li><em>constantBlock</em> is the simulation's copy of the joint constant block.</li> +<li><em>bA2w</em> is the transform of the first body. It is the identity transform if the actor is static, or a NULL pointer was supplied in constraint creation.</li> +<li><em>bB2w</em> is the transform of the second body. It is the identity transform if the actor is static, or a NULL pointer was supplied in constraint creation.</li> +</ul> +<p>The role of the solver preparation function is to populate the buffer of Px1DConstraints, provide the point of application for force reporting, and provide the mass scaling properties. The return value is the number of Px1DConstraints generated in the output buffer.</p> +<p>Notice that although the joint parameters (relative pose etc) are typically specified relative to an actor, the solver preparation function works with the transforms of the underlying rigid bodies. The constraint infrastructure (see <a class="reference internal" href="#constraint-infrastructure"><em>Data Management</em></a>) assists joints in maintaining consistency when, for example, the application modifies the center of mass of an actor.</p> +<p>Each Px1D constraint constrains one degree of freedom between the two bodies. The structure looks like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Px1DConstraint</span> +<span class="p">{</span> + <span class="n">PxVec3</span> <span class="n">linear0</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">geometricError</span><span class="p">;</span> + <span class="n">PxVec3</span> <span class="n">angular0</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">velocityTarget</span><span class="p">;</span> + + <span class="n">PxVec3</span> <span class="n">linear1</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">minImpulse</span><span class="p">;</span> + <span class="n">PxVec3</span> <span class="n">angular1</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">maxImpulse</span><span class="p">;</span> + + <span class="k">union</span> + <span class="p">{</span> + <span class="k">struct</span> <span class="n">SpringModifiers</span> + <span class="p">{</span> + <span class="n">PxReal</span> <span class="n">stiffness</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">damping</span><span class="p">;</span> + <span class="p">}</span> <span class="n">spring</span><span class="p">;</span> + <span class="k">struct</span> <span class="n">RestitutionModifiers</span> + <span class="p">{</span> + <span class="n">PxReal</span> <span class="n">restitution</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">velocityThreshold</span><span class="p">;</span> + <span class="p">}</span> <span class="n">bounce</span><span class="p">;</span> + <span class="p">}</span> <span class="n">mods</span><span class="p">;</span> + + <span class="n">PxReal</span> <span class="n">forInternalUse</span><span class="p">;</span> + <span class="n">PxU16</span> <span class="n">flags</span><span class="p">;</span> + <span class="n">PxU16</span> <span class="n">solveHint</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Each Px1DConstraint is either a hard constraint (for example, one axis of a fixed joint) or a soft constraint (for example, a spring). A joint may have a mixture of hard and soft constraint rows - for example, the actuated joint at a rag doll shoulder often has:</p> +<ul class="simple"> +<li>3 hard 1D-constraints which prevent the shoulder from separating.</li> +<li>3 hard 1D-constraints constraining the angular degrees of freedom within some limits.</li> +<li>3 soft constraints simulating resistance to angular motion from muscles.</li> +</ul> +<p>The constraint is treated as hard unless the Px1DConstraintFlag::eSPRING flag is set.</p> +<p>For both soft and hard constraints, the <em>solver velocity</em> for each row is the quantity:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">v</span> <span class="o">=</span> <span class="n">body0vel</span><span class="p">.</span><span class="n">dot</span><span class="p">(</span><span class="n">lin0</span><span class="p">,</span> <span class="n">ang0</span><span class="p">)</span> <span class="o">-</span> <span class="n">body1vel</span><span class="p">.</span><span class="n">dot</span><span class="p">(</span><span class="n">lin1</span><span class="p">,</span> <span class="n">ang1</span><span class="p">)</span> +</pre></div> +</div> +<div class="section" id="hard-constraints"> +<h5>Hard Constraints<a class="headerlink" href="#hard-constraints" title="Permalink to this headline">¶</a></h5> +<p>For a hard constraint, the solver attempts to generate:</p> +<ul> +<li><p class="first">a set of motion solver velocities vMotion for objects which, when integrated, respect the constraint errors, represented by the equation:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">vMotion</span> <span class="o">+</span> <span class="p">(</span><span class="n">geometricError</span> <span class="o">/</span> <span class="n">timestep</span><span class="p">)</span> <span class="o">=</span> <span class="n">velocityTarget</span> +</pre></div> +</div> +</li> +<li><p class="first">a set of post-simulation solver velocities vNext for the objects which respect the constraints:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">vNext</span> <span class="o">=</span> <span class="n">velocityTarget</span> +</pre></div> +</div> +</li> +</ul> +<p>The motion velocities are used for integration and then discarded. The post-simulation velocities are the values that getLinearVelocity() and getAngularVelocity() return.</p> +<p>There are two special options for hard constraints, both most often used to implement limits: restitution and velocity biasing. They are set by the constraint flags eRESTITUTION and eKEEPBIAS, are mutually exclusive, and restitution takes priority (in the sense that if restitution is set, biasing is ignored).</p> +<p>Restitution simulates bouncing (off a limit, for example). If the impact solver velocity vCurrent at the start of simulation exceeds the restitution velocity threshold, the target velocity of the constraint will be set to:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">restitution</span> <span class="o">*</span> <span class="o">-</span><span class="n">vCurrent</span> +</pre></div> +</div> +<p>and the input velocityTarget field will be ignored. To use restitution, set Px1DConstraintFlag::eRESTITUTION.</p> +<p>Velocity biasing generates post-simulation velocities to satisfy the same constraints as for the motion velocities:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">vNext</span> <span class="o">+</span> <span class="p">(</span><span class="n">geometricError</span> <span class="o">/</span> <span class="n">timestep</span><span class="p">)</span> <span class="o">=</span> <span class="n">velocityTarget</span> +</pre></div> +</div> +<p>This can be useful if, for example, the joint is approaching a limit but has not yet reached it. If the target velocity is 0 and the geometric error is the distance remaining to the limit, the solver will constrain the velocity below that required to violate the limit after integration. The joint should then converge smoothly to the limit.</p> +</div> +<div class="section" id="soft-constraints"> +<h5>Soft Constraints<a class="headerlink" href="#soft-constraints" title="Permalink to this headline">¶</a></h5> +<p>Alternatively, the solver can attempt to resolve the velocity constraint as an implicit spring. In this case, the motion velocity vMotion and post-simulation velocity vNext are the same. The solver solves the equation:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span> <span class="o">=</span> <span class="n">stiffness</span> <span class="o">*</span> <span class="o">-</span><span class="n">geometricError</span> <span class="o">+</span> <span class="n">damping</span> <span class="o">*</span> <span class="p">(</span><span class="n">velocityTarget</span> <span class="o">-</span> <span class="n">v</span><span class="p">)</span> +</pre></div> +</div> +<p>where F is the constraint force.</p> +<p>Springs are fully implicit: that is, the force or acceleration is a function of the position and velocity after the solve. There is one special option that applies only to soft constraints: acceleration springs (PxConstraintFlag::eACCELERATION). With this option the solver will scale the magnitude of the force in accordance with the response of the two bodies; effectively it implicitly solves the equation:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">acceleration</span> <span class="o">=</span> <span class="n">stiffness</span> <span class="o">*</span> <span class="o">-</span><span class="n">geometricError</span> <span class="o">+</span> <span class="n">damping</span> <span class="o">*</span> <span class="p">(</span><span class="n">velocityTarget</span> <span class="o">-</span> <span class="n">v</span><span class="p">)</span> +</pre></div> +</div> +</div> +<div class="section" id="force-limits-and-reporting"> +<h5>Force Limits and Reporting<a class="headerlink" href="#force-limits-and-reporting" title="Permalink to this headline">¶</a></h5> +<p>All constraints support limits on the minimum or maximum impulse applied for each row. There is a special flag for force limits: eHAS_DRIVE_FORCE_LIMIT. If this flag is set, the force limits will be scaled by the timestep unless PxConstraintFlag::eLIMITS_ARE_FORCES is set for the constraint.</p> +<p>The flag eOUTPUT_FORCE flag on a 1D constraint determines whether the force applied for this row should be included in the constraint force output. The reporting force is also used internally to determine joint breakage. For example, if creating a spherical joint with angular drive that breaks when the stress on the linear part exceeds a threshold, set the flag for the linear equality rows but not the angular drive rows.</p> +</div> +<div class="section" id="solver-preprocessing"> +<h5>Solver Preprocessing<a class="headerlink" href="#solver-preprocessing" title="Permalink to this headline">¶</a></h5> +<p>The joint solver attempts to preprocess hard constraints to improve convergence. The solveHint value controls preprocessing for each row:</p> +<ul class="simple"> +<li>if the constraint is a hard equality constraint with unbounded impulse limits (i.e. the impulse limits are -PX_MAX_FLT and PX_MAX_FLT), set this to PxConstraintSolveHint::eEQUALITY.</li> +<li>If one of the force limits is zero and the other unbounded, set it to PxConstraintSolveHint::eINEQUALITY.</li> +<li>for all soft constraints, and hard constraints with impulse limits other than the above, set it to PxConstraintSolveHint::eNONE.</li> +</ul> +<p>The solver does not check that the hint value is consistent with the values in the Px1DConstraint. Using inconsistent values may result in undefined behavior.</p> +</div> +</div> +<div class="section" id="the-projection-function"> +<h4>The Projection Function<a class="headerlink" href="#the-projection-function" title="Permalink to this headline">¶</a></h4> +<p>The other behavior that joints may specify for simulation is <em>projection</em>. This is a purely positional correction designed to act when the velocity-based solver fails. The projection function has the following signature:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span><span class="n">PxConstraintProject</span><span class="p">)(</span><span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> + <span class="n">PxTransform</span><span class="o">&</span> <span class="n">bodyAToWorld</span><span class="p">,</span> + <span class="n">PxTransform</span><span class="o">&</span> <span class="n">bodyBToWorld</span><span class="p">,</span> + <span class="kt">bool</span> <span class="n">projectToA</span><span class="p">);</span> +</pre></div> +</div> +<p>It receives the constant block and the two body transforms. It should update the bodyBToWorld transform if the projectToA flag is set, and otherwise the bodyBToWorld transform. See the implementations in the extensions library for examples of how to define projection functions.</p> +</div> +</div> +<div class="section" id="the-constraint-shader-table"> +<h3>The Constraint Shader Table<a class="headerlink" href="#the-constraint-shader-table" title="Permalink to this headline">¶</a></h3> +<p>After coding the behavior functions, define a structure of type PxConstraintShaderTable, which holds the pointers to the constraint functions. This structure will be passed as an argument to PxPhysics::createConstraint, and is shared by all instances of the joint:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">PxConstraintShaderTable</span> +<span class="p">{</span> + <span class="n">PxConstraintSolverPrep</span> <span class="n">solverPrep</span><span class="p">;</span> + <span class="n">PxConstraintProject</span> <span class="n">project</span><span class="p">;</span> + <span class="n">PxConstraintVisualize</span> <span class="n">visualize</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The constraint visualizer allows the joint to generate visualization information using the PxConstraintVisualizer interface. The functionality of this interface is somewhat biased towards the standard joints; examples of its use can be found in the extensions library.</p> +</div> +<div class="section" id="data-management"> +<span id="constraint-infrastructure"></span><h3>Data Management<a class="headerlink" href="#data-management" title="Permalink to this headline">¶</a></h3> +<p>Next, define the class which lets PhysX manage the joint. This class should inherit from the PxConstraintConnector interface.</p> +<p>To create a joint, call PxPhysics::createConstraint. The arguments to this function are the constrained actors, the connector object, the shader table, and the size of the joint's constant block. The return value is a pointer to PxConstraint object.</p> +<p>PxConstraintConnector has a number of data management callbacks:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span><span class="o">*</span> <span class="nf">prepareData</span><span class="p">();</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="nf">onConstraintRelease</span><span class="p">();</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="nf">onComShift</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">actor</span><span class="p">);</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="nf">onOriginShift</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">shift</span><span class="p">);</span> +<span class="k">virtual</span> <span class="kt">void</span><span class="o">*</span> <span class="nf">getExternalReference</span><span class="p">(</span><span class="n">PxU32</span><span class="o">&</span> <span class="n">typeID</span><span class="p">);</span> +</pre></div> +</div> +<p>These functions are usually boilerplate; sample implementations can be found for the joints in the extensions library:</p> +<ul class="simple"> +<li>The prepareData() function requests a pointer to the joint constant block, and allows the joint to update any state caches etc. When the function returns, the scene makes an internal copy of this data, so that the joint may be modified during simulation without race conditions. The function is called at the start of the simulation step after the joint is inserted into the scene, and on a subsequent simulation step if PhysX is informed that the joint's state has changed. To inform PhysX that the joint state has changed, call PxConstraint::markDirty().</li> +<li>onConstraintRelease() is associated with joint deletion. To delete a joint, call PxConstraint::release() on the constraint. When it is safe to destroy the joint (because no internal references are being held by currently executing simulation threads) the constraint code will call PxConstraint::onConstraintRelease(). This function can safely run the destructor and release the joint's memory etc.</li> +<li>onComShift() is called when the application calls setCMassLocalPose() on one of the actors connected by the joint. This is provided because the solver preparation and projection functions are defined using the frame of the underlying rigid body, but the joint configuration is typically defined in terms of the actors.</li> +<li>onOriginShift() is called when the application shifts the origin of a scene. This is necessary because some joints may have a NULL actor, signifying that they are attached to the world frame.</li> +<li>getExternalReference() is used by PhysX to report simulation events involving constraints, particularly breakage. The returned pointer is passed directly to the application in the event callback, along with the typeID which the application can use in order to cast the pointer to the appropriate type. The typeID should be distinct for each custom joint type, and different from any of the values in PxJointConcreteType. If the joint also implements the PxBase interface, use the concrete type value from PxBase for the typeID.</li> +</ul> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Joints</a><ul> +<li><a class="reference internal" href="#joint-basics">Joint Basics</a><ul> +<li><a class="reference internal" href="#visualization">Visualization</a></li> +<li><a class="reference internal" href="#force-reporting">Force Reporting</a></li> +<li><a class="reference internal" href="#breakage">Breakage</a></li> +<li><a class="reference internal" href="#projection">Projection</a></li> +<li><a class="reference internal" href="#limits">Limits</a></li> +<li><a class="reference internal" href="#actuation">Actuation</a></li> +<li><a class="reference internal" href="#mass-scaling">Mass Scaling</a></li> +</ul> +</li> +<li><a class="reference internal" href="#fixed-joint">Fixed Joint</a></li> +<li><a class="reference internal" href="#spherical-joint">Spherical Joint</a></li> +<li><a class="reference internal" href="#revolute-joint">Revolute Joint</a></li> +<li><a class="reference internal" href="#prismatic-joint">Prismatic Joint</a></li> +<li><a class="reference internal" href="#distance-joint">Distance Joint</a></li> +<li><a class="reference internal" href="#d6-joint">D6 Joint</a><ul> +<li><a class="reference internal" href="#locking-and-unlocking-axes">Locking and Unlocking Axes</a></li> +<li><a class="reference internal" href="#id2">Limits</a></li> +<li><a class="reference internal" href="#drives">Drives</a></li> +<li><a class="reference internal" href="#configuring-joints-for-best-behavior">Configuring Joints for Best Behavior</a></li> +</ul> +</li> +<li><a class="reference internal" href="#custom-constraints">Custom Constraints</a><ul> +<li><a class="reference internal" href="#defining-constraint-behavior">Defining Constraint Behavior</a><ul> +<li><a class="reference internal" href="#the-solver-preparation-function">The Solver Preparation Function</a><ul> +<li><a class="reference internal" href="#hard-constraints">Hard Constraints</a></li> +<li><a class="reference internal" href="#soft-constraints">Soft Constraints</a></li> +<li><a class="reference internal" href="#force-limits-and-reporting">Force Limits and Reporting</a></li> +<li><a class="reference internal" href="#solver-preprocessing">Solver Preprocessing</a></li> +</ul> +</li> +<li><a class="reference internal" href="#the-projection-function">The Projection Function</a></li> +</ul> +</li> +<li><a class="reference internal" href="#the-constraint-shader-table">The Constraint Shader Table</a></li> +<li><a class="reference internal" href="#data-management">Data Management</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="AdvancedCollisionDetection.html" + title="previous chapter">Advanced Collision Detection</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Articulations.html" + title="next chapter">Articulations</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" /> + <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="Articulations.html" title="Articulations" + >next</a></li> + <li class="right" > + <a href="AdvancedCollisionDetection.html" title="Advanced Collision Detection" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationFrom28.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationFrom28.html new file mode 100644 index 00000000..fc970b2d --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationFrom28.html @@ -0,0 +1,545 @@ +<!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>Migrating From PhysX SDK 2.x to 3.x — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Migrating From PhysX SDK 3.2 to 3.3" href="MigrationTo33.html" /> + <link rel="prev" title="Best Practices Guide" href="BestPractices.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="MigrationTo33.html" title="Migrating From PhysX SDK 3.2 to 3.3" + accesskey="N">next</a></li> + <li class="right" > + <a href="BestPractices.html" title="Best Practices Guide" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="migrating-from-physx-sdk-2-x-to-3-x"> +<span id="migration"></span><h1>Migrating From PhysX SDK 2.x to 3.x<a class="headerlink" href="#migrating-from-physx-sdk-2-x-to-3-x" title="Permalink to this headline">¶</a></h1> +<p>This guide describes how to upgrade applications that have an integration of PhysX 2.x to using PhysX 3.x. As the changes are numerous and significant, the level of work involved in upgrading to PhysX 3 should be carefully assessed before starting to adapt an application's integration code.</p> +<div class="section" id="removed-features"> +<h2>Removed Features<a class="headerlink" href="#removed-features" title="Permalink to this headline">¶</a></h2> +<p>This section lists features of PhysX 2 that do not have a PhysX 3 equivalent. Applications that rely on these features may need fundamental changes, or should stay with using PhysX 2.</p> +<div class="section" id="compartments"> +<h3>Compartments<a class="headerlink" href="#compartments" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2 scenes supported scene compartments. A separate compartment could be assigned to simulating rigid bodies, deformables or fluids. +The compartments could be simulated in parallel and the scene code contained some extra logic for interaction between compartments. +Compartments were added as an afterthought to an SDK that was not originally designed to support interaction between multiple simulation technologies. +This design deficiency was addressed from the ground up in PhysX 3 and comparments were no longer needed.</p> +<p>One missing detail is separate time steps are no longer directly supported in 3. A possible workaround is to create multiple PxScenes and step them +at different rates. In this scenario the force exchange implementation would be entirely up to the user. Another possible approach is to simulate +the entire scene using the minimum timestep formerly required for any of the compartments.</p> +</div> +<div class="section" id="deformables"> +<h3>Deformables<a class="headerlink" href="#deformables" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2 supported a wide range of deformable mesh simulation features such as environmental cloth, soft bodies, inflatable balloons and plastic +deformation of rigid metal. For performance and code quality reasons, 3.3 temporarily stopped supporting many of 2.8 deformable features in favor +of a much simpler and higher performance cloth simulation engine. In PhysX 3 dot releases, we will be incrementally adding back features such +as environmental simulation. For the time being there is no substitute for many applications of PhysX 2 deformables.</p> +</div> +<div class="section" id="nxutillib"> +<h3>NxUtilLib<a class="headerlink" href="#nxutillib" title="Permalink to this headline">¶</a></h3> +<p>The assorted utility functions that were in this library was either moved elsewhere or deleted. Sweep, overlap and ray tests are available in PxGeometryQuery. Inertial tensor diagonalization is in PxDiagonalize(). Density computation from mass is gone. Floating point unit manipulation routines are gone. Geometrical helpers are in general gone.</p> +</div> +<div class="section" id="anisotropic-friction"> +<h3>Anisotropic Friction<a class="headerlink" href="#anisotropic-friction" title="Permalink to this headline">¶</a></h3> +<p>Friction on a surface in PhysX 2 could be configured to be stronger in one direction than in another. This is no longer supported in PhysX 3, and there is no known workaround that will give comparable behavior.</p> +</div> +</div> +<div class="section" id="basics"> +<h2>Basics<a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2> +<div class="section" id="sdk-header"> +<h3>SDK Header<a class="headerlink" href="#sdk-header" title="Permalink to this headline">¶</a></h3> +<p>In PhysX 2, the symbols of the SDK could be included in the user's relevant source files through the following header:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "NxPhysics.h"</span> +</pre></div> +</div> +<p>In PhysX 3, this should be replaced with:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "PxPhysicsAPI.h"</span> +</pre></div> +</div> +</div> +<div class="section" id="sdk-redistribution"> +<h3>SDK Redistribution<a class="headerlink" href="#sdk-redistribution" title="Permalink to this headline">¶</a></h3> +<p>Unlike versions of PhysX prior to 2.8.4, PhysX 3 no longer needs a 'system software' installation on Windows.</p> +</div> +<div class="section" id="api-conventions"> +<h3>API Conventions<a class="headerlink" href="#api-conventions" title="Permalink to this headline">¶</a></h3> +<p>The Nx prefix of API classes has changed to a Px prefix. Descriptors for many classes were removed and replaced with creation parameters inline in the creation function.</p> +<p>For example, a capsule was created with PhysX 2 like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">NxCapsuleShapeDesc</span> <span class="n">capsuleDesc</span><span class="p">;</span> +<span class="n">capsuleDesc</span><span class="p">.</span><span class="n">height</span> <span class="o">=</span> <span class="n">height</span><span class="p">;</span> +<span class="n">capsuleDesc</span><span class="p">.</span><span class="n">radius</span> <span class="o">=</span> <span class="n">radius</span><span class="p">;</span> +<span class="n">capsuleDesc</span><span class="p">.</span><span class="n">materialIndex</span><span class="o">=</span> <span class="n">myMaterial</span><span class="o">-></span><span class="n">getMaterialIndex</span><span class="p">();</span> +<span class="n">NxShape</span><span class="o">*</span> <span class="n">aCapsuleShape</span> <span class="o">=</span> <span class="n">aCapsuleActor</span><span class="o">-></span><span class="n">createShape</span><span class="p">(</span><span class="n">capsuleDesc</span><span class="p">);</span> +</pre></div> +</div> +<p>In PhysX 3 it is created more succinctly like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">aCapsuleShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">aCapsuleActor</span><span class="p">,</span> + <span class="n">PxCapsuleGeometry</span><span class="p">(</span><span class="n">radius</span><span class="p">,</span> <span class="n">halfHeight</span><span class="p">),</span> <span class="n">myMaterial</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="callback-classes"> +<h3>Callback Classes<a class="headerlink" href="#callback-classes" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2 callback classes are listed below, followed by the corresponding PhysX 3 class, if there is one:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="29%" /> +<col width="71%" /> +</colgroup> +<tbody valign="top"> +<tr class="row-odd"><td>NxUserAllocator</td> +<td>PxAllocatorCallback</td> +</tr> +<tr class="row-even"><td>NxUserOutputStream</td> +<td>PxErrorCallback</td> +</tr> +<tr class="row-odd"><td>NxUserContactReport</td> +<td>PxSimulationEventCallback</td> +</tr> +<tr class="row-even"><td>NxUserNotify</td> +<td>PxSimulationEventCallback</td> +</tr> +<tr class="row-odd"><td>NxUserTriggerReport</td> +<td>PxSimulationEventCallback</td> +</tr> +</tbody> +</table> +<p>The following PhysX 2 callback classes have no PhysX 3 direct equivalent:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="18%" /> +<col width="82%" /> +</colgroup> +<tbody valign="top"> +<tr class="row-odd"><td>NxUserRaycastReport</td> +<td>Ray casting Results. Results are now passed to the user using a PxHitBuffer object.</td> +</tr> +<tr class="row-even"><td>NxUserEntityReport</td> +<td>Sweep and Overlap results. Results are now passed to the user using a PxHitBuffer object.</td> +</tr> +<tr class="row-odd"><td>NxStream</td> +<td>Data serialization. Serialized data is now written directly to binary buffers.</td> +</tr> +</tbody> +</table> +<p>Below is a list of new callback classes that offer functionality that did not exist in PhysX 2 yet:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="32%" /> +<col width="68%" /> +</colgroup> +<tbody valign="top"> +<tr class="row-odd"><td>PxBroadPhaseCallback</td> +<td>Broad-phase related events.</td> +</tr> +<tr class="row-even"><td>PxSimulationFilterCallback</td> +<td>Contact filtering.</td> +</tr> +<tr class="row-odd"><td>PxUserControllerHitReport</td> +<td>Reports character controller events.</td> +</tr> +<tr class="row-even"><td>PxControllerBehaviorCallback</td> +<td>Customizes behavior of character controller collisions.</td> +</tr> +<tr class="row-odd"><td>PxContactModifyCallback</td> +<td>Modification of contact constraints.</td> +</tr> +<tr class="row-even"><td>PxCCDContactModifyCallback</td> +<td>Modification of CCD contact constraints.</td> +</tr> +<tr class="row-odd"><td>PxConstraintConnector</td> +<td>Custom constraints.</td> +</tr> +<tr class="row-even"><td>PxProcessPxBaseCallback</td> +<td>Serialization.</td> +</tr> +<tr class="row-odd"><td>PxQueryFilterCallback</td> +<td>Scene query filtering.</td> +</tr> +<tr class="row-even"><td>PxSpatialLocationCallback</td> +<td>Scene Queries against PxSpatialIndex.</td> +</tr> +<tr class="row-odd"><td>PxSpatialOverlapCallback</td> +<td>Scene Queries against PxSpatialIndex.</td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="memory-management"> +<h3>Memory Management<a class="headerlink" href="#memory-management" title="Permalink to this headline">¶</a></h3> +<p>NxUserAllocator is renamed to PxAllocatorCallback. An important change since PhysX 2: The SDK now requires that the memory that is returned be 16-byte aligned. On many platforms malloc() returns memory that is 16-byte aligned, but on Windows the system function _aligned_malloc() provides this capability.</p> +</div> +<div class="section" id="debug-rendering"> +<h3>Debug Rendering<a class="headerlink" href="#debug-rendering" title="Permalink to this headline">¶</a></h3> +<p>Debug visualization formerly provided by NxScene::getDebugRenderable() is now handled by PxScene::getRenderBuffer() and related functions.</p> +</div> +<div class="section" id="error-reporting"> +<h3>Error Reporting<a class="headerlink" href="#error-reporting" title="Permalink to this headline">¶</a></h3> +<p>NxUserOutputStream is now called PxErrorCallback, but works the same way. There is no separate reportAssertViolation() function. Asserts are only contained in the debug build which only ships with the source release and go directly to platform hooks.</p> +</div> +<div class="section" id="type-casting"> +<h3>Type Casting<a class="headerlink" href="#type-casting" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2 style downcasting:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">NxSphereShape</span> <span class="o">*</span> <span class="n">sphere</span> <span class="o">=</span> <span class="n">shape</span><span class="o">-></span><span class="n">isSphere</span><span class="p">();</span> +</pre></div> +</div> +<p>is replaced by the following template syntax:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">myActor</span> <span class="o">=</span> <span class="n">actor</span><span class="o">-></span><span class="n">is</span><span class="o"><</span><span class="n">PxRigidDynamic</span><span class="o">></span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="multithreading"> +<h3>Multithreading<a class="headerlink" href="#multithreading" title="Permalink to this headline">¶</a></h3> +<p>Compared to PhysX 2, there are now more situations where it is legal to call the SDK from multiple threads. See the section on Multithreading for details.</p> +<p>While PhysX 2 simulation threads were managed internally by the SDK, and the user could simply specify the number to use, PhysX 3 allows the application to take over all of the simulation's thread scheduling. It is also possible for the application to define its own tasks and submit them to the SDK's default scheduler. See the section on TaskManagement for details.</p> +</div> +<div class="section" id="startup-and-shutdown"> +<h3>Startup and Shutdown<a class="headerlink" href="#startup-and-shutdown" title="Permalink to this headline">¶</a></h3> +<p>PxCreatePhysicsSDK() has been renamed PxCreatePhysics(), and the parameters have slightly changed. A foundation instance must first be created explicitly using PxCreateFoundation().</p> +</div> +<div class="section" id="extensions"> +<h3>Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h3> +<p>A lot of non-essential utility code has been moved to the extensions library. For example, NxActor::addForceAtPos() is now exposed as PxRigidBodyExt::addForceAtPos(). If a former function appears to be missing, look there. It is available after calling PxInitExtensions().</p> +</div> +<div class="section" id="heightfields"> +<h3>Heightfields<a class="headerlink" href="#heightfields" title="Permalink to this headline">¶</a></h3> +<p>Heightfields now need to be pre-cooked like convexes and meshes. PhysX 3 heightfields can be set to use the same internal collision logic as meshes so they have uniform behavior.</p> +</div> +<div class="section" id="cooking"> +<h3>Cooking<a class="headerlink" href="#cooking" title="Permalink to this headline">¶</a></h3> +<p>The PhysX 2 cooking library was created by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">NxCookingInterface</span> <span class="o">*</span><span class="n">gCooking</span> <span class="o">=</span> <span class="n">NxGetCookingLib</span><span class="p">(</span><span class="n">NX_PHYSICS_SDK_VERSION</span><span class="p">);</span> +<span class="n">gCooking</span><span class="o">-></span><span class="n">NxInitCooking</span><span class="p">();</span> +</pre></div> +</div> +<p>It can now be accessed through a single PxCreateCooking() call. Cooking function names are slightly changed, e.g. NxCookTriangleMesh() is now invoked as cooking.cookTriangleMesh().</p> +</div> +<div class="section" id="serialization"> +<h3>Serialization<a class="headerlink" href="#serialization" title="Permalink to this headline">¶</a></h3> +<p>PhysX 3 has two serialization systems: 'RepX' based on XML, and a separate system for fast binary data. Neither approach is similar to PhysX 2's save-to-desc and load-from-desc based serialization code, though the PhysX 3 'RepX' serialization is similar to PhysX 2's NxUStream.</p> +</div> +</div> +<div class="section" id="api-design-changes"> +<h2>API Design Changes<a class="headerlink" href="#api-design-changes" title="Permalink to this headline">¶</a></h2> +<div class="section" id="changed-actor-hierarchy"> +<h3>Changed Actor Hierarchy<a class="headerlink" href="#changed-actor-hierarchy" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2 only had a single actor class, and it was possible to call any method on any instance of this class even if it wasn't applicable to the kind of actor object in question. For example, isSleeping() could be called on static actors which did not have any sleep logic. In PhysX 3, we decoupled actor into a hierarchy of specialized sub-classes. For example, PxCloth and PxParticleSystem are now subclasses of PxActor.</p> +</div> +<div class="section" id="actor-creation"> +<h3>Actor Creation<a class="headerlink" href="#actor-creation" title="Permalink to this headline">¶</a></h3> +<p>In PhysX 2, the objects inside each scene were created by the scene class itself. In PhysX 3, objects are created by PxPhysics, and need to be added to a scene as a separate subsequent step by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mScene</span><span class="o">-></span><span class="n">addActor</span><span class="p">(</span><span class="n">actor</span><span class="p">);</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="material-indexes"> +<h2>Material Indexes<a class="headerlink" href="#material-indexes" title="Permalink to this headline">¶</a></h2> +<p>PhysX 2 uses so-called material indexes for stored materials. Material indices are supported in PhysX 3 only to specify per-triangle materials in meshes and heightfields. In other cases the material object is referenced directly.</p> +</div> +<div class="section" id="continuous-collision-detection"> +<h2>Continuous Collision Detection<a class="headerlink" href="#continuous-collision-detection" title="Permalink to this headline">¶</a></h2> +<p>PhysX 2 uses CCD skeleton meshes for CCD. PhysX 3 no longer needs this data so all skeleton related code can simply be removed.</p> +</div> +<div class="section" id="pose-description"> +<h2>Pose Description<a class="headerlink" href="#pose-description" title="Permalink to this headline">¶</a></h2> +<p>In PhysX 2 pose is specified using a matrix. In PhysX 3, pose is specified using a PxTransform type that consists of a PxVec3 for translation and a PxQuat for rotation. +Constructors are provided to convert 4x4 matrices to PxTransform objects and 3x3 matrices from quaternions, as well as conversely.</p> +</div> +<div class="section" id="shape-description"> +<h2>Shape Description<a class="headerlink" href="#shape-description" title="Permalink to this headline">¶</a></h2> +<p>PhysX 2 has multiple subclasses of NxShape, one for each type of geometry, with corresponding NxShapeDesc classes. PhysX 3 has only a single PxShape class, to which a PxGeometry +object is passed on creation. To determine the geometry type of a shape, call PxShape::getGeometryType(). To extract a PxGeometry object from a shape of unknown type, use +PxShape::getGeometry().</p> +<div class="section" id="skin-width"> +<h3>Skin Width<a class="headerlink" href="#skin-width" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2's NX_SKIN_WIDTH and NxShapeDesc::skinWidth was replaced with PxShape::setContactOffset() and setRestOffset(). See <a class="reference internal" href="AdvancedCollisionDetection.html#shapecollisiontuning"><em>Tuning Shape Collision Behavior</em></a>.</p> +</div> +</div> +<div class="section" id="joints"> +<h2>Joints<a class="headerlink" href="#joints" title="Permalink to this headline">¶</a></h2> +<p>The D6 driveType in PhysX 2 no longer exists in PhysX 3. Now drive for D6 is +always spring-like: if you want position drive you set the 'spring' value non-zero, if you want velocity +drive you set the damping field non-zero, and if you set both you get a damped spring. +Some specialized joints like NxJointDriveDesc, NxJointLimitSoftDesc (PhysX 2 names) now were +moved to Extensions (see the extensions folder inside PhysX 3 include directory).</p> +<p>If you have used the deleted NxSpringAndDamperEffector, you should now use a joint with a spring property.</p> +<p>All special axes for a joint (rotation axis for revolute, translation axis for prismatic, twist axis for D6) now use the x-axis.</p> +<p>Joint limits now require a contact offset, which determines the distance from the limit at which it becomes active. It functions similarly to the +contactOffset parameter for collision detection.</p> +</div> +<div class="section" id="time-stepping"> +<h2>Time Stepping<a class="headerlink" href="#time-stepping" title="Permalink to this headline">¶</a></h2> +<p>PhysX 2 had two different time stepping modes: NX_TIMESTEP_FIXED (SDK subdivided into fixes steps) and NX_TIMESTEP_VARIABLE (user specified steps). This was passed to the setTiming() function. This controlled SDK-internal substepping code that computed the proper size of the next time step, and called an internal simulate function with this elapsed time.</p> +<p>PhysX 3 discards with the substepping code altogether, and exposes only the internal simulate function directly:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mScene</span><span class="o">-></span><span class="n">simulate</span><span class="p">(</span><span class="n">mStepSize</span><span class="p">);</span> +</pre></div> +</div> +<p>In PhysX 2 it was legal to call simulate with a timestep of zero to force the execution of various side-effects of simulation. PhysX 3 neither requires nor supports this.</p> +<p>The fetchResults function stayed the same, however there is no more flag to specify which simulation to fetch, as there is now only a single simulation.</p> +<div class="section" id="simulation-parameters"> +<h3>Simulation Parameters<a class="headerlink" href="#simulation-parameters" title="Permalink to this headline">¶</a></h3> +<p>The global speeds below which objects go to sleep, NX_DEFAULT_SLEEP_LIN_VEL_SQUARED and NX_DEFAULT_SLEEP_ANG_VEL_SQUARED are gone. PhysX 3 instead features per-body function PxRigidDynamic::setSleepThreshold() which is an energy based setting, more similar to the PhysX 2 NX_DEFAULT_SLEEP_ENERGY.</p> +<p>The global NX_BOUNCE_THRESHOLD is replaced by PxSceneDesc::bounceThresholdVelocity.</p> +<p>The NX_DYN_FRICT_SCALING, NX_STA_FRICT_SCALING scaling factors have been removed. These values should now be pre-baked into friction coefficients.</p> +<p>The NX_MAX_ANGULAR_VELOCITY value has been removed.</p> +<p>NX_ADAPTIVE_FORCE has been renamed PxScenFlag.ADAPTIVE_FORCE.</p> +</div> +</div> +<div class="section" id="collision-filtering"> +<h2>Collision Filtering<a class="headerlink" href="#collision-filtering" title="Permalink to this headline">¶</a></h2> +<p>PhysX 2 supported multiple fixed function mechanisms for filtering pairwise shape collisions such as collision groups. +In PhysX 2 multiple group tags could be created, specified as collidable with each other and assigned to shapes.</p> +<p>PhysX 3, supports user callbacks for collision filtering with a restriction that arbitrary memory cannot be accessed by filtering code +so that it can be executed on PS3 SPUs or on GPUs with optimal performance. If performance is not a priority, similar functionality can be achieved +via conventional callbacks (PxSimulationFilterCallback).</p> +<p>When migrating PhysX 2 code, note that we provide the class PxDefaultSimulationFilterShader in PhysX 3, which emulates a portion of PhysX 2 filtering behavior. Start by checking if this class is sufficient. As this is an extension class, the source code is available and may be extended or customized.</p> +<p>To migrate your fixed function PhysX 2 filtering code on your own, you need to be aware of its exact behavior and implement it as a callback or shader. Let us look at the precise 2.8 mechanisms and make some recommendations for porting:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">NxScene</span><span class="o">::</span><span class="n">setShapePairFlags</span><span class="p">(</span><span class="n">NxShape</span><span class="o">&</span> <span class="n">shapeA</span><span class="p">,</span> + <span class="n">NxShape</span><span class="o">&</span> <span class="n">shapeB</span><span class="p">,</span> + <span class="n">NxU32</span> <span class="n">nxContactPairFlag</span> <span class="c1">//0 or NX_IGNORE_PAIR</span> +<span class="p">)</span> + +<span class="k">virtual</span> <span class="kt">void</span> <span class="n">NxScene</span><span class="o">::</span><span class="n">setActorPairFlags</span><span class="p">(</span><span class="n">NxActor</span><span class="o">&</span> <span class="n">actorA</span><span class="p">,</span> + <span class="n">NxActor</span><span class="o">&</span> <span class="n">actorB</span><span class="p">,</span> + <span class="n">NxU32</span> <span class="n">nxContactPairFlag</span> +<span class="p">)</span> +</pre></div> +</div> +<p>The first function stored explicit shape pairs in a hash, and a lookup returned the bit indicating to filter or not. The second did the same for actor pairs. Because of the arbitrary size of the pair hash, implementing this mechanism as a shader with fixed memory is difficult in practice, but implementing as a callback should be trivial using a data structure such as the STL hash_map where Key is a struct holding the two pointers and Data is the bit flag.</p> +<p>Another scheme provided by PhysX 2 were collision groups:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">NxShape</span><span class="o">::</span><span class="n">setGroup</span><span class="p">(</span><span class="n">NxCollisionGroup</span> <span class="n">collisionGroup</span><span class="p">)</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="n">NxScene</span><span class="o">::</span><span class="n">setGroupCollisionFlag</span><span class="p">(</span><span class="n">NxCollisionGroup</span> <span class="n">group1</span><span class="p">,</span> + <span class="n">NxCollisionGroup</span> <span class="n">group2</span><span class="p">,</span> + <span class="kt">bool</span> <span class="n">enable</span> +<span class="p">)</span> +</pre></div> +</div> +<p>This approach let the user assign shapes to one of 32 collision groups, and then let each pair of groups be assigned a boolean pair flag. This approach lends itself better to a shader based implementation. To do this, you should reserve a word of each shape's filterData (say word0) to hold the group index, +and assign this as before. Next, define a matrix to hold the group pair bits, and a function to set it:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">NxU32</span> <span class="n">groupCollisionFlags</span><span class="p">[</span><span class="mi">32</span><span class="p">];</span> + +<span class="c1">//init all group pairs to true:</span> +<span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</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">32</span><span class="p">;</span> <span class="n">i</span> <span class="o">++</span><span class="p">)</span> + <span class="n">groupCollisionFlags</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mh">0xffffffff</span><span class="p">;</span> + + +<span class="kt">void</span> <span class="nf">setU32CollisionFlag</span><span class="p">(</span><span class="n">NxU32</span> <span class="n">groups1</span><span class="p">,</span> <span class="n">NxU32</span> <span class="n">groups2</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">enable</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">NX_ASSERT</span><span class="p">(</span><span class="n">groups1</span> <span class="o"><</span> <span class="mi">32</span> <span class="o">&&</span> <span class="n">groups2</span> <span class="o"><</span> <span class="mi">32</span><span class="p">);</span> + <span class="k">if</span> <span class="p">(</span><span class="n">enable</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">//be symmetric:</span> + <span class="n">groupCollisionFlags</span><span class="p">[</span><span class="n">groups1</span><span class="p">]</span> <span class="o">|=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="n">groups2</span><span class="p">);</span> + <span class="n">groupCollisionFlags</span><span class="p">[</span><span class="n">groups2</span><span class="p">]</span> <span class="o">|=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="n">groups1</span><span class="p">);</span> + <span class="p">}</span> + <span class="k">else</span> + <span class="p">{</span> + <span class="n">groupCollisionFlags</span><span class="p">[</span><span class="n">groups1</span><span class="p">]</span> <span class="o">&=</span> <span class="o">~</span><span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="n">groups2</span><span class="p">);</span> + <span class="n">groupCollisionFlags</span><span class="p">[</span><span class="n">groups2</span><span class="p">]</span> <span class="o">&=</span> <span class="o">~</span><span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="n">groups1</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Unfortunately it is not possible to change this state after the scene is created. This is because if the matrix could change during simulation, it would force an arbitrary amount of existing contact pairs to be refiltered. In a large simulation, this could be an unacceptable amount of computation. Therefore the matrix must be initialized to its final state before the scene is created, like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSceneDesc</span> <span class="n">desc</span><span class="p">;</span> +<span class="p">...</span> +<span class="n">desc</span><span class="p">.</span><span class="n">filterShaderData</span> <span class="o">=</span> <span class="n">groupCollisionFlags</span><span class="p">;</span> +<span class="n">desc</span><span class="p">.</span><span class="n">filterShaderDataSize</span> <span class="o">=</span> <span class="mi">32</span> <span class="o">*</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">PxU32</span><span class="p">);</span> +<span class="n">scene</span> <span class="o">=</span> <span class="n">sdk</span><span class="p">.</span><span class="n">createScene</span><span class="p">(</span><span class="n">desc</span><span class="p">);</span> +</pre></div> +</div> +<p>Finally, you need to code the filter shader to access this data:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxFilterFlags</span> <span class="nf">FilterShader</span><span class="p">(</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes0</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData0</span><span class="p">,</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes1</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData1</span><span class="p">,</span> + <span class="n">PxPairFlags</span><span class="o">&</span> <span class="n">pairFlags</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">constantBlockSize</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">// let triggers through, and do any other prefiltering you need.</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxFilterObjectIsTrigger</span><span class="p">(</span><span class="n">attributes0</span><span class="p">)</span> <span class="o">||</span> <span class="n">PxFilterObjectIsTrigger</span><span class="p">(</span><span class="n">attributes1</span><span class="p">))</span> + <span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eTRIGGER_DEFAULT</span><span class="p">;</span> + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">;</span> + <span class="p">}</span> + <span class="c1">// generate contacts for all that were not filtered above</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eCONTACT_DEFAULT</span><span class="p">;</span> + + <span class="n">PxU32</span> <span class="n">ShapeGroup0</span> <span class="o">=</span> <span class="n">filterData0</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="mi">31</span><span class="p">;</span> + <span class="n">PxU32</span> <span class="n">ShapeGroup1</span> <span class="o">=</span> <span class="n">filterData1</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="mi">31</span><span class="p">;</span> + <span class="n">PxU32</span><span class="o">*</span> <span class="n">groupCollisionFlags</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxU32</span><span class="o">*</span><span class="p">)</span><span class="n">constantBlock</span><span class="p">;</span> + + <span class="k">if</span> <span class="p">((</span><span class="n">groupCollisionFlags</span><span class="p">[</span><span class="n">ShapeGroup0</span><span class="p">]</span> <span class="o">&</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="n">ShapeGroup1</span><span class="p">))</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eSUPPRESS</span><span class="p">;</span> + <span class="k">else</span> + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="scene-queries"> +<h2>Scene Queries<a class="headerlink" href="#scene-queries" title="Permalink to this headline">¶</a></h2> +<p>The API for scene query functions that return multiple intersections (e.g. PxScene::raycast(...)) has changed. +In PhysX 3, raycast/overlap/sweep functions expect a pre-allocated buffer or a callback class as a parameter in order to return multiple intersections. +If you do not know the maximum number of intersections in advance you can inherit from PxHitCallback and override processTouches virtual function +to receive an arbitrary number of intersections via multiple callbacks using only a fixed size buffer. +Please refer to the Scene Query section of the guide for more details and examples.</p> +<div class="section" id="raycasts"> +<h3>Raycasts<a class="headerlink" href="#raycasts" title="Permalink to this headline">¶</a></h3> +<p>The interface for making raycasts was changed in PhysX 3. Now you should pass an origin (PxVec3) and +a direction (PxVec3) instead of a NxRay that combined these fields in PhysX 2.</p> +</div> +<div class="section" id="overlaps"> +<h3>Overlaps<a class="headerlink" href="#overlaps" title="Permalink to this headline">¶</a></h3> +<p>Routines like overlapSphereShapes, overlapAABBShapes, overlapOBBShapes, overlapCapsuleShapes are +now all covered with PxScene::overlap (passing in a PxSphereGeometry, PxBoxGeometry or +PxCapsuleGeometry as a first parameter).</p> +</div> +<div class="section" id="sweep-tests"> +<h3>Sweep Tests<a class="headerlink" href="#sweep-tests" title="Permalink to this headline">¶</a></h3> +<p>PhysX 2 provides a linearCapsuleSweep that takes two points to define the capsule's two spherical ends. +In PhysX 3 we have a general sweep() routine that takes a PxGeometry and an initial PxTransform position. +Capsules were defined in PhysX 2 as two points. They should be converted to an initial transformation (PxTransform) that consists of +PxVec3 for position and PxQuat for rotation. PxCapsuleGeometry's length is along the x axis in local space.</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Migrating From PhysX SDK 2.x to 3.x</a><ul> +<li><a class="reference internal" href="#removed-features">Removed Features</a><ul> +<li><a class="reference internal" href="#compartments">Compartments</a></li> +<li><a class="reference internal" href="#deformables">Deformables</a></li> +<li><a class="reference internal" href="#nxutillib">NxUtilLib</a></li> +<li><a class="reference internal" href="#anisotropic-friction">Anisotropic Friction</a></li> +</ul> +</li> +<li><a class="reference internal" href="#basics">Basics</a><ul> +<li><a class="reference internal" href="#sdk-header">SDK Header</a></li> +<li><a class="reference internal" href="#sdk-redistribution">SDK Redistribution</a></li> +<li><a class="reference internal" href="#api-conventions">API Conventions</a></li> +<li><a class="reference internal" href="#callback-classes">Callback Classes</a></li> +<li><a class="reference internal" href="#memory-management">Memory Management</a></li> +<li><a class="reference internal" href="#debug-rendering">Debug Rendering</a></li> +<li><a class="reference internal" href="#error-reporting">Error Reporting</a></li> +<li><a class="reference internal" href="#type-casting">Type Casting</a></li> +<li><a class="reference internal" href="#multithreading">Multithreading</a></li> +<li><a class="reference internal" href="#startup-and-shutdown">Startup and Shutdown</a></li> +<li><a class="reference internal" href="#extensions">Extensions</a></li> +<li><a class="reference internal" href="#heightfields">Heightfields</a></li> +<li><a class="reference internal" href="#cooking">Cooking</a></li> +<li><a class="reference internal" href="#serialization">Serialization</a></li> +</ul> +</li> +<li><a class="reference internal" href="#api-design-changes">API Design Changes</a><ul> +<li><a class="reference internal" href="#changed-actor-hierarchy">Changed Actor Hierarchy</a></li> +<li><a class="reference internal" href="#actor-creation">Actor Creation</a></li> +</ul> +</li> +<li><a class="reference internal" href="#material-indexes">Material Indexes</a></li> +<li><a class="reference internal" href="#continuous-collision-detection">Continuous Collision Detection</a></li> +<li><a class="reference internal" href="#pose-description">Pose Description</a></li> +<li><a class="reference internal" href="#shape-description">Shape Description</a><ul> +<li><a class="reference internal" href="#skin-width">Skin Width</a></li> +</ul> +</li> +<li><a class="reference internal" href="#joints">Joints</a></li> +<li><a class="reference internal" href="#time-stepping">Time Stepping</a><ul> +<li><a class="reference internal" href="#simulation-parameters">Simulation Parameters</a></li> +</ul> +</li> +<li><a class="reference internal" href="#collision-filtering">Collision Filtering</a></li> +<li><a class="reference internal" href="#scene-queries">Scene Queries</a><ul> +<li><a class="reference internal" href="#raycasts">Raycasts</a></li> +<li><a class="reference internal" href="#overlaps">Overlaps</a></li> +<li><a class="reference internal" href="#sweep-tests">Sweep Tests</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="BestPractices.html" + title="previous chapter">Best Practices Guide</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="MigrationTo33.html" + title="next chapter">Migrating From PhysX SDK 3.2 to 3.3</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" /> + <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="MigrationTo33.html" title="Migrating From PhysX SDK 3.2 to 3.3" + >next</a></li> + <li class="right" > + <a href="BestPractices.html" title="Best Practices Guide" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationTo33.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationTo33.html new file mode 100644 index 00000000..07693ee6 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationTo33.html @@ -0,0 +1,1039 @@ +<!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>Migrating From PhysX SDK 3.2 to 3.3 — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Migrating From PhysX SDK 3.3 to 3.4" href="MigrationTo34.html" /> + <link rel="prev" title="Migrating From PhysX SDK 2.x to 3.x" href="MigrationFrom28.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="MigrationTo34.html" title="Migrating From PhysX SDK 3.3 to 3.4" + accesskey="N">next</a></li> + <li class="right" > + <a href="MigrationFrom28.html" title="Migrating From PhysX SDK 2.x to 3.x" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="migrating-from-physx-sdk-3-2-to-3-3"> +<span id="migrationto33"></span><h1>Migrating From PhysX SDK 3.2 to 3.3<a class="headerlink" href="#migrating-from-physx-sdk-3-2-to-3-3" title="Permalink to this headline">¶</a></h1> +<ul class="simple"> +<li>This guide highlights all significant parts of the API that have changed in the last dot release. An application with a working integration of the older version of PhysX should be able to easily migrate to the newer version by following these pointers.</li> +</ul> +<div class="section" id="math-classes"> +<h2>Math Classes<a class="headerlink" href="#math-classes" title="Permalink to this headline">¶</a></h2> +<p>The static createIdentity() and createZero() methods are now deprecated, and will be removed in a future release. The preferred method +is to use the constructors PxMat33(PxIdentity), PxMat44(PxIdentity), PxQuat(PxIdentity), PxTransform(PxIdentity) for identity transforms, and +PxMat33(PxZero) and PxMat44(PxZero) for zero matrices.</p> +</div> +<div class="section" id="scene-query-api"> +<h2>Scene Query API<a class="headerlink" href="#scene-query-api" title="Permalink to this headline">¶</a></h2> +<ul> +<li><dl class="first docutils"> +<dt>The Scene Query API underwent significant changes. The highlights are:</dt> +<dd><ul class="first last"> +<li><dl class="first docutils"> +<dt>Former raycastAny, raycastMultiple, raycastSingle API calls are now folded into a single PxScene::raycast call</dt> +<dd><ul class="first last"> +<li><p class="first">Same for overlaps and sweeps</p> +</li> +<li><p class="first">Same for PxBatchQuery and PxVolumeCache</p> +</li> +<li><dl class="first docutils"> +<dt>For PxScene queries a deprecated backwards compatibility mapping was added to aid the transition</dt> +<dd><ul class="first last simple"> +<li>This mapping will be removed in the next dot release</li> +</ul> +</dd> +</dl> +</li> +</ul> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>There are now dedicated callback and buffer classes for receiving query results, replacing PxRaycastHit array and count parameters.</dt> +<dd><ul class="first last simple"> +<li>Same for sweeps and overlaps</li> +<li>See PxRaycastBuffer, PxSweepBuffer, PxOverlapBuffer, PxRaycastCallback, PxSweepCallback, PxOverlapCallback</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first">The way results are returned is now more robust and it is possible to transparently handle unbounded number of results without dynamic allocations.</p> +</li> +<li><p class="first">Header PxSceneQueryFiltering.h was renamed to PxQueryFiltering.h, PxSceneQueryReport.h to PxQueryReport.h</p> +</li> +<li><p class="first">PxHitFlag::eIMPACT changed to PxHitFlag::ePOSITION</p> +</li> +<li><p class="first">PxRaycastHit.impact renamed to PxRaycastHit.position (same for PxSweepHit.impact)</p> +</li> +<li><p class="first">PxQueryFlag::eNO_BLOCK and PxQueryFlag::eANY_HIT flags were added</p> +</li> +<li><dl class="first docutils"> +<dt>The following classes were renamed</dt> +<dd><ul class="first last simple"> +<li>PxSceneQueryHit -> PxQueryHit</li> +<li>PxSceneQueryFlags -> PxHitFlags</li> +<li>PxSceneQueryHitType -> PxQueryHitType</li> +<li>PxSceneQueryFilterData -> PxQueryFilterData</li> +<li>PxSceneQueryFilterCallback -> PxQueryFilterCallback</li> +<li>PxSceneQueryFilterFlags -> PxQueryFlags</li> +<li>PxSceneQueryCache -> PxQueryCache</li> +<li>PxCCTNonWalkableMode -> PxControllerNonWalkableMode</li> +<li>PxControllerFlags -> PxControllerCollisionFlags</li> +<li>PxCCTHit -> PxControllerHit</li> +<li>PxConstraintDominance -> PxDominanceGroupPair</li> +<li>PxActorTypeSelectionFlags -> PxActorTypeFlags</li> +<li>PxFindOverlapTriangleMeshUtil -> PxMeshOverlapUtil</li> +<li>Old versions are #defined to new versions to simplify transition. These #defines are deprecated and will be phased out.</li> +</ul> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>queryClient parameter was removed from raycast/sweep/overlap parameter list and added to PxQueryFilterData</dt> +<dd><ul class="first last simple"> +<li>The fix is to simply pass the same value via PxQueryFilterData::clientId</li> +</ul> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>PxBatchQueryDesc now requires 3 parameters at construction time, PxU32 maxRaycastsPerExecute, PxU32 maxSweepsPerExecute, PxU32 maxOverlapsPerExecute</dt> +<dd><ul class="first last simple"> +<li>Each of these numbers is an upper bound on the number of PxBatchQuery::raycast(), sweep() and overlap() calls before a call to execute()</li> +<li>Previously there was no way to check for results buffer overflow in batch query code since sizes of these buffers were not specified.</li> +<li>The fix is to specify the batch query result (different from hit) buffer sizes at construction.</li> +</ul> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>PxBatchQueryDesc no longer directly holds pointers to memory for queries, in 3.3 these are moved to PxBatchQueryMemory.</dt> +<dd><ul class="first last simple"> +<li>It is now possible to set a new batch query memory descriptor before each execute</li> +<li>userRaycastHitBuffer has been renamed to userRaycastTouchBuffer</li> +<li>raycastHitBufferSize has been renamed to raycastTouchBufferSize</li> +<li>same for overlaps and sweeps (userSweepHitBuffer, sweepHitBufferSize, userOverlapHitBuffer, overlapHitBufferSize)</li> +<li>A code snippet below illustrates the migration for these code changes</li> +</ul> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>PxQueryFilterData constructors are now explicit. This means that previously it was possible to write</dt> +<dd><ul class="first last simple"> +<li>scene->raycast(..., PxQueryFlag::eDYNAMIC | PxQueryFlag::eSTATIC, ...), causing PxQueryFilterData to be implicitly constructed by the compiler</li> +<li>now it is required to explicitly write: scene->raycast(...,PxQueryFilterData(PxQueryFlag::eDYNAMIC | PxQueryFlag::eSTATIC), ...)</li> +<li>This change was made to improve type safety and reduce confusion while reading the code employing implicit constructors</li> +</ul> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>PxRaycastBufferN, PxOverlapBufferN and PxSweepBufferN were added for convenience</dt> +<dd><ul class="first last simple"> +<li>A buffer object with space for 10 touching hits and one blocking hit can now be conveniently declared as PxRaycastBufferN<10> hits;</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first">PxRaycastHit and PxSweepHit now inherit from PxLocationHit (formerly from PxSceneQueryImpactHit)</p> +</li> +<li><p class="first">bool PxLocationHit::hadInitialOverlap() function was added to determine if a swept shape was overlapping at sweep distance=0 or if a raycast hit a shape at distance=0.</p> +</li> +<li><p class="first">Functionality of PxSceneQueryFlag::eINITIAL_OVERLAP and PxSceneQueryFlag::eINITIAL_OVERLAP_KEEP was replaced with PxHitFlag::eASSUME_NO_INITIAL_OVERLAP and PxLocationHit::hadInitialOverlap().</p> +</li> +<li><dl class="first docutils"> +<dt>Overlap scene queries with preFilter or postFilter returning multiple eBLOCK hits would previously return multiple results as touching hits.</dt> +<dd><ul class="first last simple"> +<li>eBLOCK should not be returned from user filters for overlap(). Doing so will result in undefined behavior, and a warning will be issued.</li> +<li>If the PxQueryFlag::eNO_BLOCK flag is set, the eBLOCK will instead be automatically converted to an eTOUCH and the warning suppressed.</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first">Sweeps in 3.3 execute using a new faster code path, in some cases with reduced precision. +If you encounter precision issues not previously experienced in earlier versions of PhysX, use ePRECISE_SWEEP flag to enable +the backwards compatible more accurate sweep code.</p> +</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first">Snippets demonstrating API migration:</p> +</li> +</ul> +<p>Former raycastSingle call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastHit</span> <span class="n">hit</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">hadHit</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycastSingle</span><span class="p">(...,</span> <span class="n">hit</span><span class="p">,</span> <span class="p">...);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">hadHit</span><span class="p">)</span> <span class="n">doStuff</span><span class="p">(</span><span class="n">hit</span><span class="p">);</span> +</pre></div> +</div> +<p>Is now:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastBuffer</span> <span class="n">buf</span><span class="p">;</span> +<span class="n">Bool</span> <span class="n">hadHit</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(...,</span> <span class="n">buf</span><span class="p">,</span> <span class="p">...);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">hadHit</span><span class="p">)</span> <span class="n">doStuff</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">block</span><span class="p">);</span> +</pre></div> +</div> +<p>Former raycastAny call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSceneQueryHit</span> <span class="n">hit</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">hadHit</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycastAny</span><span class="p">(</span><span class="n">hit</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">hadHit</span><span class="p">)</span> <span class="n">doStuff</span><span class="p">(</span><span class="n">hit</span><span class="p">);</span> +</pre></div> +</div> +<p>Is now:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastBuffer</span> <span class="n">buf</span><span class="p">;</span> <span class="c1">// declare a hit buffer with room for a single blocking hit</span> +<span class="n">PxFilterData</span> <span class="n">fdAny</span><span class="p">;</span> <span class="n">fdAny</span><span class="p">.</span><span class="n">flags</span> <span class="o">|=</span> <span class="n">PxQueryFlag</span><span class="o">::</span><span class="n">eANY_HIT</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">hadHit</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="n">PxHitFlags</span><span class="p">(),</span> <span class="n">fdAny</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">hadHit</span><span class="p">)</span> <span class="n">doStuff</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">block</span><span class="p">);</span> +</pre></div> +</div> +<p>Former Multiple call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastHit</span> <span class="n">buffer</span><span class="p">[</span><span class="n">N</span><span class="p">];</span> +<span class="kt">bool</span> <span class="n">hasBlock</span><span class="p">;</span> +<span class="n">PxI32</span> <span class="n">result</span> <span class="o">=</span> <span class="n">Scene</span><span class="o">-></span><span class="n">raycastMultiple</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="n">N</span><span class="p">,</span> <span class="n">hasBlock</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">result</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> + <span class="n">handleOverflow</span><span class="p">();</span> +<span class="k">else</span> +<span class="p">{</span> + <span class="k">if</span> <span class="p">(</span><span class="n">hasBlock</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">doBlocking</span><span class="p">(</span><span class="n">buffer</span><span class="p">[</span><span class="n">result</span><span class="o">-</span><span class="mi">1</span><span class="p">]);</span> + <span class="n">doTouches</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="n">result</span><span class="o">-</span><span class="mi">1</span><span class="p">);</span> + <span class="p">}</span> + <span class="k">else</span> + <span class="p">{</span> + <span class="n">doTouches</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="n">result</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Is now:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastBufferN</span><span class="o"><</span><span class="n">N</span><span class="o">></span> <span class="n">buf</span><span class="p">;</span> +<span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">hasBlock</span><span class="p">)</span> + <span class="n">doBlocking</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">block</span><span class="p">);</span> +<span class="n">doTouches</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">touches</span><span class="p">,</span> <span class="n">buf</span><span class="p">.</span><span class="n">nbTouches</span><span class="p">);</span> +</pre></div> +</div> +<p>or:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">buf</span><span class="p">.</span><span class="n">getNbAnyHits</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="c1">// "any" in this context refers to blocking or</span> + <span class="c1">// touching hits</span> + <span class="n">doAnyHit</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">getAnyHit</span><span class="p">(</span><span class="n">i</span><span class="p">));</span> +</pre></div> +</div> +<p>Former batch query memory setup code in 3.2:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxU32</span> <span class="n">maxRaycastHits</span> <span class="o">=</span> <span class="mi">16</span><span class="p">,</span> <span class="n">maxRaycastQueries</span> <span class="o">=</span> <span class="mi">8</span><span class="p">;</span> +<span class="n">PxRaycastQueryResult</span><span class="o">*</span> <span class="n">resultBuffer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxRaycastQueryResult</span><span class="p">[</span><span class="n">maxRaycastQueries</span><span class="p">];</span> +<span class="n">PxRaycastHitBuffer</span><span class="o">*</span> <span class="n">hitBuffer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxRaycastHit</span><span class="p">[</span><span class="n">maxRaycastHits</span><span class="p">];</span> +<span class="n">PxBatchQueryDesc</span> <span class="n">desc</span><span class="p">;</span> <span class="c1">// required no arguments, there was no safety check for maximum number</span> + <span class="c1">// of queries per batch (not hits per query)</span> +<span class="n">desc</span><span class="p">.</span><span class="n">userRaycastResultBuffer</span> <span class="o">=</span> <span class="n">resultBuffer</span><span class="p">;</span> +<span class="n">desc</span><span class="p">.</span><span class="n">userRaycastHitBuffer</span> <span class="o">=</span> <span class="n">hitBuffer</span><span class="p">;</span> +<span class="n">desc</span><span class="p">.</span><span class="n">raycastHitBufferSize</span> <span class="o">=</span> <span class="n">maxRaycastHits</span><span class="p">;</span> +<span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">bq</span> <span class="o">=</span> <span class="n">PxCreateBatchQuery</span><span class="p">(</span><span class="n">desc</span><span class="p">);</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iQuery</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iQuery</span> <span class="o"><</span> <span class="n">maxRaycastQueries</span><span class="p">;</span> <span class="n">iQuery</span><span class="o">++</span><span class="p">)</span> + <span class="n">bq</span><span class="o">-></span><span class="n">raycastSingle</span><span class="p">(...);</span> <span class="c1">// up to 8 raycast queries are allowed per PxBatchQuery::execute()</span> + <span class="c1">// call but there was no overflow check in 3.2</span> +<span class="n">bq</span><span class="o">-></span><span class="n">execute</span><span class="p">();</span> + +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iResult</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iResult</span> <span class="o"><</span> <span class="n">nQueries</span><span class="p">;</span> <span class="n">iResult</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iHit</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iHit</span> <span class="o"><</span> <span class="n">resultBuffer</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">nbHits</span><span class="p">;</span> <span class="n">iHit</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="kt">bool</span> <span class="n">isBlocking</span> <span class="o">=</span> <span class="p">(</span><span class="n">iHit</span> <span class="o">==</span> <span class="n">resultBuffer</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">nbHits</span> <span class="o">&&</span> + <span class="p">(</span><span class="n">resultBuffer</span><span class="p">[</span><span class="n">iResult</span><span class="p">].</span><span class="n">hits</span><span class="p">[</span><span class="n">iHit</span><span class="p">].</span><span class="n">flags</span> <span class="o">&</span> <span class="n">PxSceneQueryFlag</span><span class="o">::</span><span class="n">eBLOCKING_HIT</span><span class="p">));</span> + <span class="n">processHit</span><span class="p">(</span><span class="n">resultBuffer</span><span class="p">[</span><span class="n">iResult</span><span class="p">].</span><span class="n">hits</span><span class="p">[</span><span class="n">iHit</span><span class="p">],</span> <span class="n">isBlocking</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Batch query setup code in 3.3:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxU32</span> <span class="n">maxRaycastHits</span> <span class="o">=</span> <span class="mi">16</span><span class="p">,</span> <span class="n">maxRaycastQueries</span> <span class="o">=</span> <span class="mi">8</span><span class="p">;</span> +<span class="n">PxBatchQueryDesc</span> <span class="nf">desc</span><span class="p">(</span><span class="n">maxQueries</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">// note the new required maximum of queries per batch</span> + <span class="c1">// (this is different from maximum hits)</span> +<span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">bq</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">createBatchQuery</span><span class="p">(</span><span class="n">desc</span><span class="p">);</span> + +<span class="n">PxRaycastQueryResult</span><span class="o">*</span> <span class="n">resultBuffer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxRaycastQueryResult</span><span class="p">[</span><span class="n">maxRaycastQueries</span><span class="p">];</span> +<span class="n">PxRaycastHitBuffer</span> <span class="n">hitBuffer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxRaycastHit</span><span class="p">[</span><span class="n">maxRaycastHits</span><span class="p">];</span> +<span class="n">PxBatchQueryMemory</span> <span class="nf">mem</span><span class="p">(</span><span class="n">maxQueries</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">// maximum number of queries for each type</span> + <span class="c1">// (raycasts, overlaps, sweeps)</span> +<span class="n">mem</span><span class="p">.</span><span class="n">userRaycastResultBuffer</span> <span class="o">=</span> <span class="n">resultBuffer</span><span class="p">;</span> +<span class="n">mem</span><span class="p">.</span><span class="n">userRaycastTouchBuffer</span> <span class="o">=</span> <span class="n">hitBuffer</span><span class="p">;</span> +<span class="n">mem</span><span class="p">.</span><span class="n">raycastTouchBufferSize</span> <span class="o">=</span> <span class="n">maxHits</span><span class="p">;</span> + +<span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">bq</span> <span class="o">=</span> <span class="n">PxCreateBatchQuery</span><span class="p">(</span><span class="n">desc</span><span class="p">);</span> +<span class="n">bq</span><span class="o">-></span><span class="n">setUserMemory</span><span class="p">(</span><span class="n">mem</span><span class="p">);</span> + +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iQuery</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iQuery</span> <span class="o"><</span> <span class="n">maxRaycastQueries</span><span class="p">;</span> <span class="n">iQuery</span><span class="o">++</span><span class="p">)</span> + <span class="n">bq</span><span class="o">-></span><span class="n">raycastSingle</span><span class="p">(...);</span> <span class="c1">// up to 8 raycast queries are allowed per PxBatchQuery::execute()</span> + <span class="c1">// with query count overflow check as of 3.3</span> +<span class="n">bq</span><span class="o">-></span><span class="n">execute</span><span class="p">();</span> + +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iResult</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iResult</span> <span class="o"><</span> <span class="n">nQueries</span><span class="p">;</span> <span class="n">iResult</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">// note that the blocking hit is now reported in resultBuffer[i].block and touching hits in</span> + <span class="c1">// resultBuffer[i].touches</span> + <span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iHit</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iHit</span> <span class="o"><</span> <span class="n">resultBuffer</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">nbTouches</span><span class="p">;</span> <span class="n">iHit</span><span class="o">++</span><span class="p">)</span> + <span class="n">processTouchingHit</span><span class="p">(</span><span class="n">resultBuffer</span><span class="p">[</span><span class="n">iResult</span><span class="p">].</span><span class="n">touches</span><span class="p">[</span><span class="n">iHit</span><span class="p">]);</span> + + <span class="n">processBlockingHit</span><span class="p">(</span><span class="n">resultBuffer</span><span class="p">[</span><span class="n">iResult</span><span class="p">].</span><span class="n">block</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="spu-batch-queries"> +<h2>SPU batch queries<a class="headerlink" href="#spu-batch-queries" title="Permalink to this headline">¶</a></h2> +<p>In 3.2 the number of SPUs to be used per batch query was controlled by a global setting via setSceneParamInt call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPS3Config</span><span class="o">::</span><span class="n">setSceneParamInt</span><span class="p">(</span><span class="n">getScene</span><span class="p">(),</span> <span class="n">PxPS3ConfigParam</span><span class="o">::</span><span class="n">eSPU_RAYCAST</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span> +</pre></div> +</div> +<p>In 3.3 PxBatchQuery no longer automatically executes on multiple SPUs but requires a separate PPU thread, this design allows higher +flexibility, such as executing batches on multiple SPU and PPU threads simultaneously, better control of parallel execution and allows the user to fine tune thread load balancing. +Here's one possible way to run batch queries on multiple SPUs in 3.3:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">BQThread</span> <span class="o">:</span> <span class="n">shdfnd</span><span class="o">::</span><span class="n">Thread</span> +<span class="p">{</span> + <span class="n">Ps</span><span class="o">::</span><span class="n">Sync</span> <span class="n">mBatchReady</span><span class="p">;</span> + <span class="n">Ps</span><span class="o">::</span><span class="n">Sync</span> <span class="n">mBatchCompleted</span><span class="p">;</span> + <span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">mBatch</span><span class="p">;</span> + + <span class="n">PX_FORCE_INLINE</span> <span class="nf">BQThread</span><span class="p">()</span> <span class="p">{</span> <span class="n">mBatch</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> <span class="p">}</span> + <span class="n">PX_FORCE_INLINE</span> <span class="kt">void</span> <span class="nf">submitBatch</span><span class="p">(</span><span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">batch</span><span class="p">)</span> <span class="p">{</span> <span class="n">mBatch</span> <span class="o">=</span> <span class="n">batch</span><span class="p">;</span> <span class="p">}</span> + + <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">execute</span><span class="p">()</span> + <span class="p">{</span> + <span class="c1">// execute submitted batches until quit is signalled</span> + <span class="k">for</span><span class="p">(;;)</span> + <span class="p">{</span> + <span class="n">mBatchReady</span><span class="p">.</span><span class="n">wait</span><span class="p">();</span> + <span class="n">mBatchReady</span><span class="p">.</span><span class="n">reset</span><span class="p">();</span> + + <span class="k">if</span> <span class="p">(</span><span class="n">quitIsSignalled</span><span class="p">())</span> + <span class="k">break</span><span class="p">;</span> + + <span class="n">mBatch</span><span class="o">-></span><span class="n">execute</span><span class="p">();</span> + + <span class="n">mBatch</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> + <span class="n">mBatchCompleted</span><span class="p">.</span><span class="n">set</span><span class="p">();</span> + <span class="p">}</span> <span class="c1">// for (;;)</span> + + <span class="n">quit</span><span class="p">();</span> <span class="c1">// shutdown thread</span> + <span class="p">}</span> +<span class="p">};</span> + +<span class="c1">// main thread code:</span> +<span class="c1">// pre-create and launch batch execute threads</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iThread</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iThread</span> <span class="o"><</span> <span class="n">nThreads</span><span class="p">;</span> <span class="n">iThread</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">BQThread</span><span class="o">*</span> <span class="n">t</span> <span class="o">=</span> <span class="n">PX_NEW</span><span class="p">(</span><span class="n">BQThread</span><span class="p">);</span> + <span class="n">t</span><span class="o">-></span><span class="n">start</span><span class="p">();</span> + <span class="n">mThreads</span><span class="p">.</span><span class="n">pushBack</span><span class="p">(</span><span class="n">t</span><span class="p">);</span> +<span class="p">}</span> + +<span class="c1">// submit batches</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">iThread</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">iThread</span> <span class="o"><</span> <span class="n">nThreads</span><span class="p">;</span> <span class="n">iThread</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">// create batches</span> + <span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">threadBatch</span> <span class="o">=</span> <span class="n">createBatch</span><span class="p">(...);</span> + <span class="n">threadBatch</span><span class="o">-></span><span class="n">setRunOnSpu</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> + + <span class="n">mThreads</span><span class="p">[</span><span class="n">iThread</span><span class="p">]</span><span class="o">-></span><span class="n">submitBatch</span><span class="p">(</span><span class="n">threadBatch</span><span class="p">);</span> + <span class="n">mThreads</span><span class="p">[</span><span class="n">iThread</span><span class="p">]</span><span class="o">-></span><span class="n">mBatchReady</span><span class="p">.</span><span class="n">set</span><span class="p">();</span> +<span class="p">}</span> + +<span class="c1">// execute another batch on PPU in the meantime.</span> +<span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">threadBatch</span> <span class="o">=</span> <span class="n">createBatch</span><span class="p">(...);</span> +<span class="n">threadBatch</span><span class="o">-></span><span class="n">setRunOnSpu</span><span class="p">(</span><span class="nb">false</span><span class="p">);</span> +<span class="n">threadBatch</span><span class="o">-></span><span class="n">execute</span><span class="p">();</span> + +<span class="c1">// do other PPU work...</span> + +<span class="c1">// wait for SPU batches to complete:</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">mThreads</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mBatchCompleted</span><span class="p">.</span><span class="n">wait</span><span class="p">();</span> + <span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mBatchCompleted</span><span class="p">.</span><span class="n">reset</span><span class="p">();</span> + <span class="n">releaseBatch</span><span class="p">(</span><span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mBatch</span><span class="p">);</span> +<span class="p">}</span> + +<span class="c1">// terminate batch threads</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">mThreads</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">signalQuit</span><span class="p">();</span> + <span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mBatchReady</span><span class="p">.</span><span class="n">set</span><span class="p">();</span> + <span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">waitForQuit</span><span class="p">();</span> + <span class="n">PX_DELETE</span><span class="p">(</span><span class="n">mThreads</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Whether the batch is executed on SPU or PPU is determined by either bool PxBatchQueryDesc::runOnSpu or PxBatchQuery::setRunOnSpu(bool), +by default batch query is executed on SPU:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxBatchQueryDesc</span> <span class="n">desc</span><span class="p">;</span> +<span class="p">...</span> +<span class="n">desc</span><span class="p">.</span><span class="n">runOnSpu</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span> +<span class="p">...</span> +</pre></div> +</div> +</div> +<div class="section" id="core-physx"> +<h2>Core PhysX<a class="headerlink" href="#core-physx" title="Permalink to this headline">¶</a></h2> +<ul> +<li><p class="first">The following methods require that the corresponding objects have been added to a scene. Calling these methods for objects which are not in a scene will result in undefined behavior. In the CHECKED build configuration an error message will get sent.</p> +<blockquote> +<div><ul class="simple"> +<li>addForce/addTorque/clearForce/clearTorque() on a PxRigidBody</li> +<li>isSleeping/wakeUp/putToSleep() on a PxRigidDynamic, PxArticulation or PxCloth</li> +<li>PxScene::resetFiltering() and the deprecated counterparts on PxShape and PxParticleBase</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">The sleep behavior of dynamic rigid bodies has changed significantly. Among the changes are:</p> +<blockquote> +<div><ul class="simple"> +<li>The wakeUp() method of PxRigidDynamic and PxArticulation has lost the wake counter parameter. Use the newly introduced method setWakeCounter() instead to set a specific value.</li> +<li>Putting a dynamic rigid actor to sleep will clear any pending force updates.</li> +<li>Switching a dynamic actor to kinematic will put the actor to sleep immediately.</li> +<li>Switching a kinematic actor back to dynamic will not affect the sleep state (previously the actor was woken up).</li> +<li>Calling wakeUp/putToSleep() on a kinematically controlled dynamic actor is not valid any longer. The sleep state of a kinematic actor is solely defined based on whether a target pose has been set (see API documentation of isSleeping() for details).</li> +<li>A call to PxRigidBody::setCMassLocalPose() does not wake up the actor anymore. Add a call to PxRigidBody::wakeUp() to get the old behavior back. Note: this also affects related methods in PhysXExtensions like PxRigidBodyExt::updateMassAndInertia() etc.</li> +<li>Adding or removing a PxConstraint to/from the scene does not wake the connected actors up automatically anymore (note: this applies to PxJoint in PhysX Extensions as well).</li> +<li>If a non-zero velocity or force is set through PxRigidBody::setLinearVelocity(), ::setAngularVelocity(), ::addForce() or ::addTorque(), the actor will get woken up automatically even if the autowake parameter is false.</li> +<li>PxRigidBody::clearForce() and ::clearTorque() do not have the autowake parameter, to optionally wake the actor up, anymore. These methods will not change the sleep state any longer. Call ::wakeUp() subsequently to get the old default behavior.</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">Shapes may now be shared between actors. This change has several ramifications:</p> +<blockquote> +<div><ul class="simple"> +<li>PxShape::getActor() now returns a pointer rather than a reference. If the shape is shareable, the pointer is NULL.</li> +<li>The following methods of PxShape have been removed: getGlobalPose(), raycast(), sweep(), overlap(), getWorldBounds(). Replacements can be found in PxShapeExt.</li> +<li>PxShape now has the same reference counting semantics as meshes and materials, so that release() releases the user reference, and when the last reference is released, the shape is destroyed.</li> +<li>Shapes created through PxRigidActor::createShape() are still destroyed automatically when the actor is released. However, after serializing and deserializing such a shape, the regular reference counting semantics apply.</li> +<li>return results from scene queries which previously specified a shape now specify an actor also.</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">Shape local transforms cannot be specified on shape creation anymore. Instead set the local transform after creation with PxShape::setLocalPose().</p> +</li> +<li><p class="first">The PxObserver/PxObservable system has been replaced by the PxDeletionListener API. The supported object types have been extended from PxActor to all core objects inheriting from PxBase. Furthermore, two kinds of deletion events are now distinguished: user release and memory release. The following snippet shows pseudocode for the transition from the previous to the new API:</p> +</li> +</ul> +<p>old API:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyObserver</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxObserver</span> +<span class="p">{</span> +<span class="nl">public:</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">onRelease</span><span class="p">(</span><span class="k">const</span> <span class="n">PxObservable</span><span class="o">&</span> <span class="n">observable</span><span class="p">);</span> +<span class="p">}</span> + +<span class="n">MyObserver</span> <span class="n">myObs</span><span class="p">;</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">d</span> <span class="o">=</span> <span class="n">create</span><span class="p">...;</span> +<span class="n">d</span><span class="o">-></span><span class="n">registerObserver</span><span class="p">(</span><span class="n">myObs</span><span class="p">);</span> +</pre></div> +</div> +<p>new API:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyDelListener</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxDeletionListener</span> +<span class="p">{</span> +<span class="nl">public:</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">onRelease</span><span class="p">(</span><span class="k">const</span> <span class="n">PxBase</span><span class="o">*</span> <span class="n">observable</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span> <span class="n">userData</span><span class="p">,</span> + <span class="n">PxDeletionEventFlag</span><span class="o">::</span><span class="n">Enum</span> <span class="n">deletionEvent</span><span class="p">);</span> +<span class="p">}</span> + +<span class="n">MyDelListener</span> <span class="n">myDelListener</span><span class="p">;</span> +<span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span> <span class="o">=</span> <span class="n">create</span><span class="p">...;</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">d</span> <span class="o">=</span> <span class="n">create</span><span class="p">...;</span> +<span class="n">physics</span><span class="o">-></span><span class="n">registerDeletionListener</span><span class="p">(</span><span class="n">myDelListener</span><span class="p">,</span> <span class="n">PxDeletionEventFlag</span><span class="o">::</span><span class="n">eUSER_RELEASE</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +<span class="n">PxBase</span><span class="o">*</span> <span class="n">b</span> <span class="o">=</span> <span class="n">d</span><span class="p">;</span> +<span class="n">physics</span><span class="o">-></span><span class="n">registerDeletionListenerObjects</span><span class="p">(</span><span class="n">myDelListener</span><span class="p">,</span> <span class="o">&</span><span class="n">b</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span> +</pre></div> +</div> +<ul> +<li><p class="first">The contactStream in PxContactPair is now stored in a variable-size compressed contact stream. This is used to save memory. As such, you can <strong>no longer</strong> simply cast it to a PxContactPoint* and access the data. Instead, you must either use PxContactPair::extractContacts or us a PxContactStreamIterator to interpret the data. Please see the callbacks section of the user guide for further information.</p> +</li> +<li><p class="first">The friction API and behavior for dynamic rigid bodies has changed slightly:</p> +<blockquote> +<div><ul class="simple"> +<li>Friction mode flags eENABLE_ONE_DIRECTIONAL_FRICTION and eENABLE_TWO_DIRECTIONAL_FRICTION have been replaced by PxFrictionType::Enum PxSceneDesc::frictionType.</li> +<li>PxSceneDesc::contactCorrelationDistance has been deprecated, and it no longer has an influence on how many friction anchors are created in a single frame, only on when they are removed in later frames. This may cause a very minor change in friction behavior.</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">PxShape::resetFiltering() and PxParticleBase::resetFiltering() have been deprecated. Please use one of the new overloaded methods PxScene::resetFiltering() instead.</p> +</li> +<li><p class="first">PxClientBehaviorBit and PxActorClientBehaviorBit have been renamed to PxClientBehaviorFlag and PxActorClientBehaviorFlag respectively.</p> +</li> +<li><p class="first">PxActorTypeSelectionFlag and PxActorTypeSelectionFlags have been renamed to PxActorTypeFlag and PxActorTypeFlags respectively.</p> +</li> +<li><p class="first">PxConstraintDominance has been renamed to PxDominanceGroupPair</p> +</li> +<li><p class="first">The parameter 'spring' on articulation joints has been renamed 'stiffness'.</p> +</li> +<li><p class="first">The parameter 'tangentialSpring' on articulation joints has been renamed 'tangentialStiffness'.</p> +</li> +<li><p class="first">PxConstraintFlag::Type has been renamed to PxConstraintFlag::Enum</p> +</li> +<li><p class="first">Discrete contact reports are no longer produced for pairs without PxPairFlag::eDETECT_DISCRETE_CONTACT raised in the filter shader. Previously, discrete contact generation would always have been performed regardless of the presence of the PxPairFlag::eDETECT_DISCRETE_CONTACT flag. This change potentially improves performance when using specific shapes for CCD-only collision, which would have previously generated discrete contacts and then ignored them in the solver.</p> +</li> +<li><p class="first">Trigger reports are no longer produced for pairs without PxPairFlag::eDETECT_DISCRETE_CONTACT raised in the filter shader. PxPairFlag::eTRIGGER_DEFAULT has been modified to include the PxPairFlag::eDETECT_DISCRETE_CONTACT flag.</p> +</li> +</ul> +</div> +<div class="section" id="physx-extensions"> +<h2>PhysX Extensions<a class="headerlink" href="#physx-extensions" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>Joint limits have been more carefully separated into PxJointLinearLimit, PxJointAngularLimitPair, PxJointLinearLimitPair.</li> +<li>PxJoint::getType() is deprecated. Joints now inherit from PxBase, and getConcreteType() replaces getType(). Alternatively, to dynamically cast to a particular joint type, use e.g. joint->is<PxD6Joint>() which will return a pointer to a D6 joint if the type matches, otherwise NULL.</li> +<li>The parameter 'spring' in joint limits and drives has been renamed 'stiffness'.</li> +<li>Dominance settings no longer apply to joints. To achieve this effect, use setInvMassScale. For example if actor0 in the joint is to affect actor1 but not conversely, use setInvMassScale0(0.0f), setInverseInertiaScale0(0.0f).</li> +</ul> +</div> +<div class="section" id="physx-character-controller"> +<h2>PhysX Character Controller<a class="headerlink" href="#physx-character-controller" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>When creating a PxControllerManager, a reference to a PxScene has to be provided. As a consequence, creating a controller from a PxControllerManager now only requires the controller descriptor as an argument.</li> +<li>On PxControllerManager::release(), all associated PxObstacleContext instances will get deleted automatically. Make sure to not access PxObstacleContext instances after the corresponding manager has been released.</li> +</ul> +</div> +<div class="section" id="physx-vehicles"> +<h2>PhysX Vehicles<a class="headerlink" href="#physx-vehicles" title="Permalink to this headline">¶</a></h2> +<ul> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleDrive4W::eFRONT_LEFT_WHEEL. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleDrive4W::eFRONT_LEFT_WHEEL -> PxVehicleDrive4WWheelOrder::eFRONT_LEFT</li> +<li>PxVehicleDrive4W::eFRONT_RIGHT_WHEEL -> PxVehicleDrive4WWheelOrder::eFRONT_RIGHT</li> +<li>PxVehicleDrive4W::eREAR_LEFT_WHEEL -> PxVehicleDrive4WWheelOrder::eREAR_LEFT</li> +<li>PxVehicleDrive4W::eREAR_RIGHT_WHEEL -> PxVehicleDrive4WWheelOrder::eREAR_RIGHT</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleDrive4WControl::eANALOG_INPUT_ACCEL. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleDrive4W::eANALOG_INPUT_ACCEL -> PxVehicleDrive4WControl::eANALOG_INPUT_ACCEL</li> +<li>PxVehicleDrive4W::eANALOG_INPUT_BRAKE -> PxVehicleDrive4WControl::eANALOG_INPUT_BRAKE</li> +<li>PxVehicleDrive4W::eANALOG_INPUT_HANDBRAKE -> PxVehicleDrive4WControl::eANALOG_INPUT_HANDBRAKE</li> +<li>PxVehicleDrive4W::eANALOG_INPUT_STEER_LEFT -> PxVehicleDrive4WControl::eANALOG_INPUT_STEER_LEFT</li> +<li>PxVehicleDrive4W::eANALOG_INPUT_STEER_RIGHT -> PxVehicleDrive4WControl::eANALOG_INPUT_STEER_RIGHT</li> +<li>PxVehicleDrive4W::eMAX_NUM_DRIVE4W_ANALOG_INPUTS -> PxVehicleDrive4WControl::eMAX_NB_DRIVE4W_ANALOG_INPUTS</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleDrive4W::eFRONT_LEFT_WHEEL. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleDriveTank::eTANK_WHEEL_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::eFRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::eFRONT_RIGHT,</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_1ST_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e1ST_FROM_FRONT_LEFT,</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_1ST_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e1ST_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_2ND_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e2ND_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_2ND_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e2ND_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_3RD_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e3RD_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_3RD_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder:: e3RD_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_4TH_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e4TH_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_4TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e4TH_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_5TH_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e5TH_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_5TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e5TH_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_6TH_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e6TH_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_6TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e6TH_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_7TH_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e7TH_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_7TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e7TH_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_8TH_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e8TH_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_8TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e8TH_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_9TH_FROM_FRONT_LEFT -> PxVehicleDriveTankWheelOrder::e9TH_FROM_FRONT_LEFT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_9TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e9TH_FROM_FRONT_RIGHT</li> +<li>PxVehicleDriveTank::eTANK_WHEEL_9TH_FROM_FRONT_RIGHT -> PxVehicleDriveTankWheelOrder::e9TH_FROM_FRONT_RIGHT</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleDriveTank::eANALOG_INPUT_ACCEL. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleDriveTank::eANALOG_INPUT_ACCEL -> PxVehicleDriveTankControl::eANALOG_INPUT_ACCEL</li> +<li>PxVehicleDriveTank::eANALOG_INPUT_BRAKE_LEFT -> PxVehicleDriveTankControl::eANALOG_INPUT_BRAKE_LEFT</li> +<li>PxVehicleDriveTank::eANALOG_INPUT_BRAKE_RIGHT -> PxVehicleDriveTankControl::eANALOG_INPUT_BRAKE_RIGHT</li> +<li>PxVehicleDriveTank::eANALOG_INPUT_THRUST_LEFT -> PxVehicleDriveTankControl::eANALOG_INPUT_THRUST_LEFT</li> +<li>PxVehicleDriveTank::eANALOG_INPUT_THRUST_RIGHT -> PxVehicleDriveTankControl::eANALOG_INPUT_THRUST_RIGHT</li> +<li>PxVehicleDriveTank::eMAX_NUM_DRIVETANK_ANALOG_INPUTS -> PxVehicleDriveTankControl::eMAX_NB_DRIVETANK_ANALOG_INPUTS</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleDriveTank::eDRIVE_MODEL_STANDARD. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleDriveTank::eDRIVE_MODEL_STANDARD -> PxVehicleDriveTankControlModel::eSTANDARD</li> +<li>PxVehicleDriveTank::eDRIVE_MODEL_SPECIAL -> PxVehicleDriveTankControlModel::eSPECIAL</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with eVEHICLE_TYPE_DRIVE4W. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>eVEHICLE_TYPE_DRIVE4W -> PxVehicleTypes::eDRIVE4W</li> +<li>eVEHICLE_TYPE_DRIVETANK -> PxVehicleTypes::eDRIVETANK</li> +<li>eVEHICLE_TYPE_NODRIVE -> PxVehicleTypes::eNODRIVE</li> +<li>eMAX_NUM_VEHICLE_TYPES -> PxVehicleTypes::eMAX_NB_VEHICLE_TYPES</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleGraph::eCHANNEL_JOUNCE. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleGraph::eCHANNEL_JOUNCE -> PxVehicleWheelGraphChannel::eJOUNCE</li> +<li>PxVehicleGraph::eCHANNEL_SUSPFORCE -> PxVehicleWheelGraphChannel::eSUSPFORCE</li> +<li>PxVehicleGraph::eCHANNEL_TIRELOAD -> PxVehicleWheelGraphChannel::eTIRELOAD</li> +<li>PxVehicleGraph::eCHANNEL_NORMALIZED_TIRELOAD -> PxVehicleWheelGraphChannel::eNORMALIZED_TIRELOAD</li> +<li>PxVehicleGraph::eCHANNEL_WHEEL_OMEGA -> PxVehicleWheelGraphChannel::eWHEEL_OMEGA</li> +<li>PxVehicleGraph::eCHANNEL_TIRE_FRICTION -> PxVehicleWheelGraphChannel::eTIRE_FRICTION</li> +<li>PxVehicleGraph::eCHANNEL_TIRE_LONG_SLIP -> PxVehicleWheelGraphChannel::eTIRE_LONG_SLIP</li> +<li>PxVehicleGraph::eCHANNEL_NORM_TIRE_LONG_FORCE -> PxVehicleWheelGraphChannel::eNORM_TIRE_LONG_FORCE</li> +<li>PxVehicleGraph::eCHANNEL_TIRE_LAT_SLIP -> PxVehicleWheelGraphChannel::eTIRE_LAT_SLIP</li> +<li>PxVehicleGraph::eCHANNEL_NORM_TIRE_LAT_FORCE -> PxVehicleWheelGraphChannel::eNORM_TIRE_LAT_FORCE</li> +<li>PxVehicleGraph::eCHANNEL_NORM_TIRE_ALIGNING_MOMENT -> PxVehicleWheelGraphChannel::eNORM_TIRE_ALIGNING_MOMENT</li> +<li>PxVehicleGraph::eMAX_NUM_WHEEL_CHANNELS -> PxVehicleWheelGraphChannel::eMAX_NB_WHEEL_CHANNELS</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleGraph::eCHANNEL_ENGINE_REVS. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleGraph::eCHANNEL_ENGINE_REVS -> PxVehicleDriveGraphChannel::eENGINE_REVS</li> +<li>PxVehicleGraph::eCHANNEL_ENGINE_DRIVE_TORQUE -> PxVehicleDriveGraphChannel::eENGINE_DRIVE_TORQUE</li> +<li>PxVehicleGraph::eCHANNEL_CLUTCH_SLIP -> PxVehicleDriveGraphChannel::eCLUTCH_SLIP</li> +<li>PxVehicleGraph::eCHANNEL_ACCEL_CONTROL -> PxVehicleDriveGraphChannel::eACCEL_CONTROL</li> +<li>PxVehicleGraph::eCHANNEL_BRAKE_CONTROL -> PxVehicleDriveGraphChannel::eBRAKE_CONTROL</li> +<li>PxVehicleGraph::eCHANNEL_HANDBRAKE_CONTROL -> PxVehicleDriveGraphChannel::eHANDBRAKE_CONTROL</li> +<li>PxVehicleGraph::eCHANNEL_STEER_LEFT_CONTROL -> PxVehicleDriveGraphChannel::eSTEER_LEFT_CONTROL</li> +<li>PxVehicleGraph::eCHANNEL_STEER_RIGHT_CONTROL -> PxVehicleDriveGraphChannel::eSTEER_RIGHT_CONTROL</li> +<li>PxVehicleGraph::eCHANNEL_GEAR_RATIO -> PxVehicleDriveGraphChannel::eGEAR_RATIO</li> +<li>PxVehicleGraph::eMAX_NUM_ENGINE_CHANNELS -> PxVehicleDriveGraphChannel::eMAX_NB_DRIVE_CHANNELS</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">A new struct has been introduced to hold the enumerated list that began with PxVehicleGraph::eGRAPH_TYPE_WHEEL. The changes are</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleGraph::eGRAPH_TYPE_WHEEL -> PxVehicleGraphType::eWHEEL</li> +<li>PxVehicleGraph::eGRAPH_TYPE_ENGINE -> PxVehicleGraphType::eDRIVE</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">Non-persistent data is no longer stored in the vehicle. Instead of storing this data in each vehicle it is stored in an array and passed to PxVehicleUpdates as an extra function argument. A simple example of how to construct, use, and read this data is given below. This example code updates an array of vehicles and tests if they are in the air. If the vehicles are not in the air then the actor under each wheel is recorded and stored in an array:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">updateVehicles</span><span class="p">(</span><span class="k">const</span> <span class="n">PxF32</span> <span class="n">timestep</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">gravity</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVehicleDrivableSurfaceToTireFrictionPairs</span><span class="o">&</span> <span class="n">fricPairs</span><span class="p">,</span> + <span class="n">PxVehicleWheels</span><span class="o">**</span> <span class="n">vehicles</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">numVehicles</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">PxActor</span><span class="o">*>&</span> <span class="n">hitActors</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//Count the total number of wheels.</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">numWheels</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + <span class="k">for</span><span class="p">(</span><span class="kt">unsigned</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">numVehicles</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">numWheels</span> <span class="o">+=</span> <span class="n">vehicles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getNbWheels</span><span class="p">();</span> + <span class="p">}</span> + + <span class="c1">//Allocate buffers to store results for each vehicle and each wheel.</span> + <span class="n">PxVehicleWheelQueryResult</span><span class="o">*</span> <span class="n">vehicleWheelQueryResults</span> <span class="o">=</span> + <span class="k">new</span> <span class="n">PxVehicleWheelQueryResult</span><span class="p">[</span><span class="n">numVehicles</span><span class="p">];</span> + <span class="n">PxWheelQueryResult</span><span class="o">*</span> <span class="n">wheelQueryResults</span> <span class="o">=</span> <span class="k">new</span> <span class="n">PxWheelQueryResult</span><span class="p">[</span><span class="n">numWheels</span><span class="p">];</span> + <span class="n">PxU32</span> <span class="n">wheelCount</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numVehicles</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">vehicleWheelQueryResults</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">nbWheelQueryResults</span> <span class="o">=</span> + <span class="n">vehicles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getNbWheels</span><span class="p">();</span> + <span class="n">vehicleWheelQueryResults</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">wheelQueryResults</span> <span class="o">=</span> <span class="o">&</span><span class="n">wheelQueryResults</span><span class="p">[</span><span class="n">wheelCount</span><span class="p">];</span> + <span class="n">wheelCount</span> <span class="o">+=</span> <span class="n">vehicles</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getNbWheels</span><span class="p">();</span> + <span class="p">}</span> + + <span class="c1">//Update the array of vehicles.</span> + <span class="n">PxVehicleUpdates</span><span class="p">(</span><span class="n">timestep</span><span class="p">,</span> <span class="n">gravity</span><span class="p">,</span> <span class="n">fricPairs</span><span class="p">,</span> <span class="n">numVehicles</span><span class="p">,</span> <span class="n">vehicles</span><span class="p">,</span> + <span class="n">vehicleWheelQueryResults</span><span class="p">);</span> + + <span class="c1">//Test if each vehicle is in the air.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numVehicles</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">PxVehicleIsInAir</span><span class="p">(</span><span class="n">vehicleWheelQueryResults</span><span class="p">[</span><span class="n">i</span><span class="p">]))</span> + <span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">j</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">j</span> <span class="o"><</span> <span class="n">vehicleWheelQueryResults</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">nbWheelQueryResults</span><span class="p">;</span> <span class="n">j</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">vehicleWheelQueryResults</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">wheelQueryResults</span><span class="p">[</span><span class="n">j</span><span class="p">].</span><span class="n">tireContactActor</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">hitActors</span><span class="p">.</span><span class="n">push_back</span> + <span class="p">(</span><span class="n">vehicleWheelQueryResults</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">wheelQueryResults</span><span class="p">[</span><span class="n">j</span><span class="p">].</span><span class="n">tireContactActor</span><span class="p">);</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="p">}</span> + + <span class="k">delete</span><span class="p">[]</span> <span class="n">vehicleWheelQueryResults</span><span class="p">;</span> + <span class="k">delete</span><span class="p">[]</span> <span class="n">wheelQueryResults</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +</li> +<li><p class="first">The following accessors to non-persistent data associated with each wheel have been replaced as follows</p> +<blockquote> +<div><ul class="simple"> +<li>PxVehicleWheelsDynData::getSuspLineStart -> PxWheelQueryResult::suspLineStart</li> +<li>PxVehicleWheelsDynData::getSuspLineDir -> PxWheelQueryResult::suspLineDir</li> +<li>PxVehicleWheels::getSuspRaycast -> PxWheelQueryResult::suspLineStart, PxWheelQueryResult::suspLineDir, PxWheelQueryResult::suspLineLength</li> +<li>PxVehicleWheelsDynData::getTireDrivableSurfaceShape -> PxWheelQueryResult::tireContactShape</li> +<li>PxVehicleWheelsDynData::getTireDrivableSurfaceMaterial -> PxWheelQueryResult::tireSurfaceMaterial</li> +<li>PxVehicleWheelsDynData::getTireDrivableSurfaceType -> PxWheelQueryResult::tireSurfaceType</li> +<li>PxVehicleWheelsDynData::getTireDrivableSurfaceContactPoint -> PxWheelQueryResult::tireContactPoint</li> +<li>PxVehicleWheelsDynData::getTireDrivableSurfaceContactNormal -> PxWheelQueryResult::tireContactNormal</li> +<li>PxVehicleWheelsDynData::getTireFriction -> PxWheelQueryResult::tireFriction</li> +<li>PxVehicleWheelsDynData::getSuspJounce -> PxWheelQueryResult::suspJounce</li> +<li>PxVehicleWheelsDynData::getSuspensionForce -> PxWheelQueryResult::suspSpringForce</li> +<li>PxVehicleWheelsDynData::getTireLongitudinalDir -> PxWheelQueryResult::tireLongitudinalDir</li> +<li>PxVehicleWheelsDynData::getTireLateralDir -> PxWheelQueryResult::tireLateralDir</li> +<li>PxVehicleWheelsDynData::getTireLongSlip -> PxWheelQueryResult::longitudinalSlip</li> +<li>PxVehicleWheelsDynData::getTireLatSlip ->PxWheelQueryResult::lateralSlip</li> +<li>PxVehicleWheelsDynData::getSteer -> PxWheelQueryResult::steerAngle</li> +<li>PxVehicleWheels::isInAir -> PxWheelQueryResult::isInAir</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">PxVehicleWheels::setWheelShapeMapping and PxVehicleWheels::getWheelShapeMapping have been moved to PxVehicleWheelsSimData::setWheelShapeMapping and PxVehicleWheelsSimData::getWheelShapeMapping</p> +</li> +<li><p class="first">PxVehicleWheels::setSceneQueryFilterData and PxVehicleWheels::getSceneQueryFilterData have been moved to PxVehicleWheelsSimData::setSceneQueryFilterData and PxVehicleWheelsSimData::getSceneQueryFilterData</p> +</li> +<li><p class="first">PxVehicle4WEnable3WTadpoleMode and PxVehicle4WEnable3WDeltaMode now take an extra function argument: a non-const reference to a PxVehicleWheelsDynData</p> +</li> +<li><p class="first">PxVehicleWheels::isInAir() has been replaced with PxVehicleIsInAir(const PxVehicleWheelQueryResult& vehWheelQueryResults)</p> +</li> +<li><p class="first">PxVehicleDrive4WSmoothAnalogRawInputsAndSetAnalogInputs now takes an extra function argument "const bool isVehicleInAir". This can be calculated using the function PxVehicleIsInAir</p> +</li> +<li><p class="first">To improve api consistency PxVehicleTelemetryData::getNumWheelGraphs is now PxVehicleTelemetryData::getNbWheelGraphs</p> +</li> +<li><p class="first">To improve api consistency PX_MAX_NUM_WHEELS is now PX_MAX_NB_WHEELS</p> +</li> +<li><p class="first">To improve api consistency PxVehicleGraph::eMAX_NUM_TITLE_CHARS is now PxVehicleGraph::eMAX_NB_TITLE_CHARS</p> +</li> +<li><p class="first">PxVehicleTireData::mCamberStiffness has been replaced with PxVehicleTireData::mCamberStiffnessPerUnitGravity. PxVehicleTireData::mCamberStiffnessPerUnitGravity should be set so that it is equivalent to the old value of PxVehicleTireData::mCamberStiffness divided by the magnitude of gravitational acceleration (PxScene::getGravity().magnitude()). The advantage of using PxVehicleTireData::mCamberStiffnessPerUnitGravity is that it independent of length scale.</p> +</li> +<li><p class="first">PxVehicleComputeTireForceDefault has been removed from the public vehicle api. Custom tire shaders that call PxVehicleComputeTireForceDefault are best implemented by taking a copy of PxVehicleComputeTireForceDefault and calling the copy instead.</p> +</li> +</ul> +</div> +<div class="section" id="ccd"> +<h2>CCD<a class="headerlink" href="#ccd" title="Permalink to this headline">¶</a></h2> +<ul> +<li><p class="first">The mechanism to activate CCD per shape has changed in 3.3. The PxShapeFlag::eUSE_SWEPT_BOUNDS that was used in 3.2 to active swept bounds per shape has been removed. In its place is a new flag PxRigidBodyFlag::eENABLE_CCD that is set per rigid actor. Setting this flag for an actor in 3.3 has approximately the same effect as setting PxShapeFlag::eUSE_SWEPT_BOUNDS on all the actor's shapes in 3.2.</p> +</li> +<li><p class="first">PxPairFlag::eSWEPT_INTEGRATION_LINEAR has been replaced with PxPairFlag::eCCD_LINEAR in PhysX 3.3.</p> +</li> +<li><p class="first">PxSceneFlag::eENABLE_SWEPT_INTEGRATION flag in 3.2 has been replaced with PxSceneFlag::eENABLE_CCD in PhysX 3.3.</p> +</li> +<li><p class="first">A simple example of how to enable CCD on a specific shape is given below. This demonstrates creating a body consisting of a large box and a smaller sphere, where the box is only used in discrete collision detection and the sphere is only used in CCD. The simulation filter shader shown here requires that the filter data of both shapes be flagged with eCCD_RESPONSE to generate a CCD response (PxPairFlag::eCCD_LINEAR). Likewise, the filter shader shown here is configured so that the filter data of both shapes need to be flagged with eDISCRETE_RESPONSE in order to generate a collision response (PxPairFlag::eRESOLVE_CONTACTS). A final remark is that the following shader requires that shapes of static actors have filter data with flags eDISCRETE_RESPONSE | eCCD_RESPONSE in order to ensure ccd and collision response from pairs that involve a static actor and a CCD-enabled dynamic actor:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">CCDFilterTest</span> +<span class="p">{</span> + <span class="k">enum</span> <span class="n">FilterFlags</span> + <span class="p">{</span> + <span class="n">eDISCRETE_RESPONSE</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span> + <span class="n">eCCD_RESPONSE</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span> + <span class="p">};</span> + <span class="k">static</span> <span class="n">PxFilterFlags</span> <span class="nf">filterShader</span><span class="p">(</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes0</span><span class="p">,</span> + <span class="n">PxFilterData</span> <span class="n">filterData0</span><span class="p">,</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes1</span><span class="p">,</span> + <span class="n">PxFilterData</span> <span class="n">filterData1</span><span class="p">,</span> + <span class="n">PxPairFlags</span><span class="o">&</span> <span class="n">pairFlags</span><span class="p">,</span> + <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> + <span class="n">PxU32</span> <span class="n">constantBlockSize</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlags</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> + + <span class="n">PxU32</span> <span class="n">combo</span> <span class="o">=</span> <span class="n">filterData0</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData1</span><span class="p">.</span><span class="n">word0</span><span class="p">;</span> + <span class="k">if</span><span class="p">(</span><span class="n">combo</span> <span class="o">&</span> <span class="n">eDISCRETE_RESPONSE</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eRESOLVE_CONTACTS</span><span class="p">;</span> + <span class="p">}</span> + <span class="k">if</span><span class="p">(</span><span class="n">combo</span> <span class="o">&</span> <span class="n">eCCD_RESPONSE</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eCCD_LINEAR</span><span class="p">;</span> + <span class="p">}</span> + <span class="k">return</span> <span class="n">PxFilterFlags</span><span class="p">();</span> + <span class="p">}</span> +<span class="p">};</span> + +<span class="p">....</span> + +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dyn</span> <span class="o">=</span> <span class="n">getPhysics</span><span class="p">().</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="o">-</span><span class="mi">4</span><span class="p">,</span> <span class="o">-</span><span class="mf">3.5</span><span class="p">,</span> <span class="mi">0</span><span class="p">)));</span> +<span class="n">PxBoxGeometry</span> <span class="n">box</span><span class="p">;</span> +<span class="n">box</span><span class="p">.</span><span class="n">halfExtents</span> <span class="o">=</span> <span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.f</span><span class="p">,</span> <span class="mf">1.f</span><span class="p">,</span> <span class="mf">1.f</span><span class="p">);</span> +<span class="n">PxSphereGeometry</span> <span class="n">sphere</span><span class="p">;</span> +<span class="n">sphere</span><span class="p">.</span><span class="n">radius</span> <span class="o">=</span> <span class="mf">0.75f</span><span class="p">;</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">boxShape</span> <span class="o">=</span> <span class="n">dyn</span><span class="o">-></span><span class="n">createShape</span><span class="p">(</span><span class="n">box</span><span class="p">,</span> <span class="n">getDefaultMaterial</span><span class="p">());</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">sphereShape</span> <span class="o">=</span> <span class="n">dyn</span><span class="o">-></span><span class="n">createShape</span><span class="p">(</span><span class="n">sphere</span><span class="p">,</span> <span class="n">getDefaultMaterial</span><span class="p">());</span> + +<span class="n">PxFilterData</span> <span class="n">data</span> <span class="o">=</span> <span class="n">boxShape</span><span class="o">-></span><span class="n">getSimulationFilterData</span><span class="p">();</span> +<span class="n">data</span><span class="p">.</span><span class="n">word0</span> <span class="o">|=</span> <span class="n">CCDFilterTest</span><span class="o">::</span><span class="n">eDISCRETE_RESPONSE</span><span class="p">;</span> +<span class="n">boxShape</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">data</span><span class="p">);</span> + +<span class="n">data</span> <span class="o">=</span> <span class="n">sphereShape</span><span class="o">-></span><span class="n">getSimulationFilterData</span><span class="p">();</span> +<span class="n">data</span><span class="p">.</span><span class="n">word0</span> <span class="o">|=</span> <span class="n">CCDFilterTest</span><span class="o">::</span><span class="n">eCCD_RESPONSE</span><span class="p">;</span> +<span class="n">sphereShape</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">data</span><span class="p">);</span> + +<span class="n">dyn</span><span class="o">-></span><span class="n">setRigidBodyFlag</span><span class="p">(</span><span class="n">PxRigidBodyFlag</span><span class="o">::</span><span class="n">eENABLE_CCD</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +<span class="n">getActiveScene</span><span class="p">().</span><span class="n">addActor</span><span class="p">(</span><span class="o">*</span><span class="n">dyn</span><span class="p">);</span> +</pre></div> +</div> +</li> +</ul> +</div> +<div class="section" id="physx-visual-debugger"> +<h2>PhysX Visual Debugger<a class="headerlink" href="#physx-visual-debugger" title="Permalink to this headline">¶</a></h2> +<ul> +<li><dl class="first docutils"> +<dt>A new flag has been introduced to configure the visualizing of constraints:</dt> +<dd><p class="first last">PxVisualDebuggerFlag::eTRANSMIT_CONSTRAINTS;</p> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>A new function has been introduced to configure PxVisualDebugger flags:</dt> +<dd><p class="first last">PxVisualDebugger::setVisualDebuggerFlags( PxVisualDebuggerFlags flags);</p> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>A new funtion has been introduced to send error stream to PVD:</dt> +<dd><p class="first last">PxVisualDebugger::sendErrorMessage((PxErrorCode::Enum code, const char* message, const char* file, PxU32 line);</p> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>The following functions were renamed:</dt> +<dd><p class="first last">PxVisualDebugger::getPvdConnectionFactory() -> PxVisualDebugger::getPvdConnection(); +PxVisualDebugger::getPvdConnection() -> PxVisualDebugger::getPvdDataStream();</p> +</dd> +</dl> +</li> +<li><dl class="first docutils"> +<dt>The PVD connect function changed to the same method as previously 3.2 version:</dt> +<dd><p class="first last">PxVisualDebuggerExt::connect -> PxVisualDebuggerExt::createConnection;</p> +</dd> +</dl> +</li> +<li><p class="first">The constraint, contacts and scene queries visualizing can all be configed with PxVisualDebuggerFlag in 3.3. Here is an example for how to enable pvd visualizing the contacts :</p> +<blockquote> +<div><p>mPhysics->getVisualDebugger()->setVisualDebuggerFlags(PxVisualDebuggerFlag::eTRANSMIT_CONTACTS | PxVisualDebuggerFlag::eTRANSMIT_CONSTRAINTS);</p> +</div></blockquote> +</li> +</ul> +</div> +<div class="section" id="physx-cloth"> +<h2>PhysX Cloth<a class="headerlink" href="#physx-cloth" title="Permalink to this headline">¶</a></h2> +<p>There have been substantial changes to the PhysX 3.3 cloth solver that improve performance and behavior. This has resulted in +a reorganization of how constraints are stored and processed in the cloth fabric. Prior to PhysX 3.3 the cloth solver used fibers to +organize edge constraints into independent groups. In PhysX 3.3 it is no longer necessary to decompose constraints into fibers, +instead edge constraints now exist individually and are solved in larger, independent sets. Interface changes are detailed below:</p> +<ul> +<li><p class="first">Previously there were multiple solver types to choose from for each group of constraints such as eFAST, eSTIFF, eBENDING, etc (previously PxClothPhaseSolverConfig::SolverType). There is now one type of solver for all edge constraints, this is a flexible distance constraint with controls to adjust stiffness within certain ranges of compression and stretch (see PxClothStretchConfig). Behaviors such as bending are now achieved by the way distance constraints are arranged geometrically, rather than through a specialized bending solver.</p> +</li> +<li><p class="first">To reduce stretching a new constraint type has been added called "tether" constraints. These constraints do not act along edges of the mesh, but act as long range attachments between particles that enforce a maximum distance between two points. See PxClothFabric::getTetherAnchors().</p> +</li> +<li><p class="first">Cloth cooking which was previously part of the PxCooking library has been moved to the extension library, see PxClothFabricCooker:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// PhysX 3.2.x</span> +<span class="n">cooking</span><span class="o">-></span><span class="n">cookClothFabric</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="n">outputStream</span><span class="p">);</span> + +<span class="c1">// PhysX 3.3</span> +<span class="n">PxClothFabricCooker</span> <span class="nf">cooker</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="n">useGeodesicTethers</span><span class="p">);</span> +<span class="n">cooker</span><span class="p">.</span><span class="n">save</span><span class="p">(</span><span class="n">outputStream</span><span class="p">,</span> <span class="nb">false</span><span class="p">);</span> +</pre></div> +</div> +</li> +<li><p class="first">The PxClothCollisionData parameter has been removed from PxPhysx::createCloth(). The collision shapes can now be added after cloth creation using PxCloth::addCollisionSphere and PxCloth::addCollisionCapsule.</p> +</li> +<li><p class="first">PxCloth::wakeUp() does not have a parameter anymore. Use the newly introduced method setWakeCounter() instead to set a specific value.</p> +</li> +<li><p class="first">PxCloth::setDampingCoefficient now takes a PxVec3 instead of a PxReal to specify the damping per axis.</p> +</li> +<li><p class="first">PxCloth::setPhaseSolverConfig() has been renamed to PxCloth::setStretchConfig()</p> +</li> +<li><p class="first">PxCloth::lockClothReadData() has been renamed to PxCloth::lockParticleData()</p> +</li> +<li><p class="first">PxClothFabricTypes.h has been removed, this header has been merged with PxClothFabric.h</p> +</li> +</ul> +</div> +<div class="section" id="repx-serialization"> +<h2>RepX Serialization<a class="headerlink" href="#repx-serialization" title="Permalink to this headline">¶</a></h2> +<p>Substantial changes were made to the PhysX 3.3 serialization interface. Handling of collections and references between collections have been unified for RepX and binary serialization.</p> +<ul> +<li><p class="first">The RepX and RepXUpgrader libraries have been removed. RepX functionality is now provided through PhysXExtensions.</p> +</li> +<li><p class="first">RepXCollection has been replaced with PxCollection, which is the common collection class for both RepX and binary serialization in 3.3. Collections are now instantiated on deserialization with PxSerialization::createCollectionFromXml(). Empty collections can be created with PxCreateCollection(). Serialization into RepX format is achieved through PxSerialization::serializeCollectionToXml().</p> +</li> +<li><p class="first">TRepXId has been replaced with PxSerialObjectId.</p> +</li> +<li><p class="first">RepXIdToRepXObjectMap and RepXObject have been replaced with new functionality in PxCollection, which now maps between serializable objects and PxSerialObjectId values.</p> +</li> +<li><p class="first">RepXExtension was removed. Serialization and deserialization of serializable types is achieved through the PxRepXSerializer interface.</p> +</li> +<li><dl class="first docutils"> +<dt>RepXUtility and PxToolkit functionality has been replaced with various functions in PxSerialization, PxCollection and PxScene.</dt> +<dd><ul class="first last simple"> +<li>A PxCollection with all PxPhysics-level objects such as shapes, meshes or materials (formally referred to as buffers) can be created using PxCollectionExt::createCollection(PxPhysics&).</li> +<li>Similarly PxCollectionExt::createCollection(PxScene&) can be used to create a collection of PxScene-level objects.</li> +<li>Dependencies between objects and collections can be handled with PxSerialization::complete().</li> +<li>The objects of a collection can be added to a scene with PxScene::addCollection().</li> +<li>Operations on files are generally handled with abstract interfaces: PxOutputStream and PxInputData. Default implementations are available as PxDefaultFileOutputStream and PxDefaultFileInputData.</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first">RepXUpgrader::upgradeCollection was removed. RepX data can be converted to newer PhysX versions by deserializing and re-serializing a collection: PxSerialization::createCollectionFromXml(), PxSerialization::serializeCollectionToXml().</p> +</li> +<li><p class="first">Serialization functionality requires a PxSerializationRegistry instance which can be created with PxSerialization::createSerializationRegistry().</p> +</li> +<li><p class="first">XML serialization can be configured to store the cooked triangle and convex mesh data along with the plain data for faster loading.</p> +</li> +<li><p class="first">PhysXVehicles supports RepX serialization. PxSerializationRegistry needs to be provided to PxInitVehicleSDK() for vehicle serialization, PxCloseVehicleSDK() for cleanup.</p> +</li> +<li><p class="first">Custom class RepX serialization is supported in 3.3, more information please read <a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a>.</p> +</li> +</ul> +</div> +<div class="section" id="binary-serialization"> +<h2>Binary Serialization<a class="headerlink" href="#binary-serialization" title="Permalink to this headline">¶</a></h2> +<p>The binary serialization interface has been refactored and unified with the RepX serialization interface.</p> +<ul> +<li><p class="first">Most serialization functionality requires an instance of the new class PxSerializationRegistry. It is application managed and can be created with PxSerialization::createSerializationRegistry() and released with PxSerializationRegistry::release().</p> +</li> +<li><p class="first">The base class for serializable types has been renamed from PxSerializable to PxBase. Most of the serialization functionality moved to a separate PxSerializer class. A PxSerializer instance per serializable type is registered in the PxSerializationRegistry. All PhysX and PhysXExtension serializables are registered by default.</p> +</li> +<li><dl class="first docutils"> +<dt>PxCollection has been reworked.</dt> +<dd><ul class="first last simple"> +<li>PxCollection::serialize() and PxCollection::deserialize() were replaced with PxSerialization::createCollectionFromBinary() PxSerialization::serializeCollectionToBinary() in PhysXExtensions.</li> +<li>PxSerializable::collectForExport() has been replaced with PxCollection::add(). PxSerialzation::complete() helps to add required objects for resolving dependencies. PxSerializable::isSerializable() should be used check whether a collection can be successfully serialized.</li> +</ul> +</dd> +</dl> +</li> +<li><p class="first">PxUserReferences was removed: PxCollection instances can now be used directly to resolve dependencies between collections on deserialization. PxSerialization::complete() supports creating collections with external dependencies to other collections.</p> +</li> +<li><p class="first">PxSerialObjectRef has been replaced with PxSerialObjectId.</p> +</li> +<li><p class="first">PxCollectForExportSDK() and PxCollectForExportScene() functions were replaced with PxCollectionExt::createCollection(PxPhysics& physics) and PxCollectionExt::createCollection(PxScene& scene).</p> +</li> +<li><p class="first">PxDumpMetaData() was replaced with PxSerialization::dumpBinaryMetaData().</p> +</li> +<li><p class="first">The PxBinaryConverter moved from PhysXCooking to PhysXExtensions. PxCooking::createBinaryConverter() was replaced with PxSerialization::createBinaryConverter().</p> +</li> +<li><p class="first">PhysXVehicles supports binary serialization. PxSerializationRegistry needs to be provided to PxInitVehicleSDK() for vehicle serialization, PxCloseVehicleSDK() for cleanup.</p> +</li> +<li><p class="first">Custom class binary serialization is supported in 3.3, more information please read <a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a>.</p> +</li> +</ul> +</div> +<div class="section" id="physx-taskmanager"> +<h2>PhysX TaskManager<a class="headerlink" href="#physx-taskmanager" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>The pxtask namespace has been removed and all it's types are now included in the physx namespace with a Px prefix, for example pxtask::LightCpuTask has become physx::PxLightCpuTask</li> +</ul> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Migrating From PhysX SDK 3.2 to 3.3</a><ul> +<li><a class="reference internal" href="#math-classes">Math Classes</a></li> +<li><a class="reference internal" href="#scene-query-api">Scene Query API</a></li> +<li><a class="reference internal" href="#spu-batch-queries">SPU batch queries</a></li> +<li><a class="reference internal" href="#core-physx">Core PhysX</a></li> +<li><a class="reference internal" href="#physx-extensions">PhysX Extensions</a></li> +<li><a class="reference internal" href="#physx-character-controller">PhysX Character Controller</a></li> +<li><a class="reference internal" href="#physx-vehicles">PhysX Vehicles</a></li> +<li><a class="reference internal" href="#ccd">CCD</a></li> +<li><a class="reference internal" href="#physx-visual-debugger">PhysX Visual Debugger</a></li> +<li><a class="reference internal" href="#physx-cloth">PhysX Cloth</a></li> +<li><a class="reference internal" href="#repx-serialization">RepX Serialization</a></li> +<li><a class="reference internal" href="#binary-serialization">Binary Serialization</a></li> +<li><a class="reference internal" href="#physx-taskmanager">PhysX TaskManager</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="MigrationFrom28.html" + title="previous chapter">Migrating From PhysX SDK 2.x to 3.x</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="MigrationTo34.html" + title="next chapter">Migrating From PhysX SDK 3.3 to 3.4</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" /> + <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="MigrationTo34.html" title="Migrating From PhysX SDK 3.3 to 3.4" + >next</a></li> + <li class="right" > + <a href="MigrationFrom28.html" title="Migrating From PhysX SDK 2.x to 3.x" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationTo34.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationTo34.html new file mode 100644 index 00000000..ae6e2a7e --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/MigrationTo34.html @@ -0,0 +1,231 @@ +<!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>Migrating From PhysX SDK 3.3 to 3.4 — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="prev" title="Migrating From PhysX SDK 3.2 to 3.3" href="MigrationTo33.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="MigrationTo33.html" title="Migrating From PhysX SDK 3.2 to 3.3" + accesskey="P">previous</a></li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="migrating-from-physx-sdk-3-3-to-3-4"> +<span id="migrationto34"></span><h1>Migrating From PhysX SDK 3.3 to 3.4<a class="headerlink" href="#migrating-from-physx-sdk-3-3-to-3-4" title="Permalink to this headline">¶</a></h1> +<ul class="simple"> +<li>This guide highlights all significant parts of the API that have changed in the last dot release. An application with a working integration of the older version of PhysX should be able to easily migrate to the newer version by following these pointers.</li> +<li>Functionality shared with the APEX SDK was moved into a separate "PxShared" directory outside of the "PhysX" directory. Since the PxFoundation object is part of the PxShared library, it is versioned separately. PxCreateFoundation now takes PX_FOUNDATION_VERSION as an argument.</li> +</ul> +<div class="section" id="deprecated-apis"> +<h2>Deprecated APIs<a class="headerlink" href="#deprecated-apis" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pxrigidactor-createshape"> +<h3>PxRigidActor::createShape<a class="headerlink" href="#pxrigidactor-createshape" title="Permalink to this headline">¶</a></h3> +<p>PxRigidActor::createShape() is deprecated, and will be removed in PhysX 3.5. PxRigidActorExt::createExclusiveShape() replaces this method.</p> +</div> +<div class="section" id="pxsceneflag-edeprecated-trigger-trigger-reports"> +<h3>PxSceneFlag::eDEPRECATED_TRIGGER_TRIGGER_REPORTS<a class="headerlink" href="#pxsceneflag-edeprecated-trigger-trigger-reports" title="Permalink to this headline">¶</a></h3> +<p>PxSceneFlag::eDEPRECATED_TRIGGER_TRIGGER_REPORTS is deprecated, and will be removed in PhysX 3.5. More details are mentioned under <a class="reference internal" href="#migration-3-4-core-phsx"><em>Core PhysX</em></a> further below.</p> +</div> +<div class="section" id="physx-particles"> +<h3>PhysX particles<a class="headerlink" href="#physx-particles" title="Permalink to this headline">¶</a></h3> +<p>The PhysX particle feature has been deprecated in PhysX version 3.4. The standalone library PhysX FleX is an alternative with a richer feature set.</p> +</div> +</div> +<div class="section" id="core-physx"> +<span id="migration-3-4-core-phsx"></span><h2>Core PhysX<a class="headerlink" href="#core-physx" title="Permalink to this headline">¶</a></h2> +<ul> +<li><p class="first">PxCreatePhysics now requires a PxFoundation object to be passed. Optionally it receives a pointer to a PxPvd object, used for connecting PhysX with the visual debugger.</p> +</li> +<li><p class="first">PxActor::isRigidStatic, isRigidDynamic, isParticleSystem, isParticleFluid, isArticulationLink, isCloth, isRigidActor, isRigidBody, isParticleBase have been removed. Use corresponding PxBase::is() with class template parameter for down casting.</p> +</li> +<li><p class="first">PxContactPairFlag::eINTERNAL_HAS_FACE_INDICES is obsolete and has been removed.</p> +</li> +<li><p class="first">Trigger shapes will no longer send notification events for interactions with other trigger shapes. For PhysX 3.4 there is the option to re-enable the reports by raising PxSceneFlag::eDEPRECATED_TRIGGER_TRIGGER_REPORTS but this option will no longer be available in PhysX 3.5. It is recommended to not make use of eDEPRECATED_TRIGGER_TRIGGER_REPORTS and instead use a trigger and a non-trigger shape, both with the same geometry and local pose, to emulate getting notifications for overlaps between trigger shapes.</p> +</li> +<li><p class="first">Implementations of PxSimulationEventCallback will have to provide an (empty) implementation of the newly added method <em>onAdvance()</em> to avoid compilation errors.</p> +</li> +<li><p class="first">The deprecated method PxPhysics::createHeightField(const PxHeightFieldDesc&) has been removed. Please use PxCooking::createHeightField(const PxHeightFieldDesc&, PxPhysicsInsertionCallback&) instead. The insertion callback can be obtained through PxPhysics::getPhysicsInsertionCallback().</p> +</li> +<li><p class="first">The deprecated flag PxActorTypeSelectionFlag/PxActorTypeSelectionFlags has been removed. Please use PxActorTypeFlag/PxActorTypeFlags instead.</p> +</li> +<li><p class="first">The deprecated class PxFindOverlapTriangleMeshUtil has been removed. Please use PxMeshOverlapUtil instead.</p> +</li> +<li><p class="first">The deprecated flag PxConstraintFlag::eREPORTING has been removed. Force reports are now always generated.</p> +</li> +<li><p class="first">The deprecated flag PxConstraintFlag::eDEPRECATED_32_COMPATIBILITY has been removed.</p> +</li> +<li><p class="first">PxRegisterHeightFields() now registers unified heightfields. To register legacy heightfields, call PxRegisterLegacyHeightFields(). Legacy heightfield collision is deprecated and will be removed in a future PhysX release.</p> +</li> +<li><p class="first">The following deprecated simulation event flags have been removed:</p> +<blockquote> +<div><ul> +<li><p class="first">PxContactPairHeaderFlag::eDELETED_ACTOR_0, ::eDELETED_ACTOR_1</p> +<p>(use PxContactPairHeaderFlag::eREMOVED_ACTOR_0, ::eREMOVED_ACTOR_1 instead)</p> +</li> +<li><p class="first">PxContactPairFlag::eDELETED_SHAPE_0, ::eDELETED_SHAPE_1</p> +<p>(use PxContactPairFlag::eREMOVED_SHAPE_0, ::eREMOVED_SHAPE_1 instead)</p> +</li> +<li><p class="first">PxTriggerPairFlag::eDELETED_SHAPE_TRIGGER, ::eDELETED_SHAPE_OTHER</p> +<p>(use PxTriggerPairFlag::eREMOVED_SHAPE_TRIGGER, ::REMOVED_SHAPE_OTHER instead)</p> +</li> +</ul> +</div></blockquote> +</li> +<li><p class="first">PxContactPair now reports separate pointers for contactPatches, contactPoints and contactImpulses rather than reporting a single pointer that the PxContactStreamIterator parses. The interface for PxContactStreamIterator has been modified accordingly. See the PxContactPair::extractContacts implementation for further guidance on how to iterate over this contact data if required.</p> +</li> +</ul> +</div> +<div class="section" id="contact-generation"> +<h2>Contact Generation<a class="headerlink" href="#contact-generation" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>PCM contact generation is now used by default. Legacy SAT-based contact generation can be re-enabled by clearing the PxSceneFlag::eENABLE_PCM from PxSceneDesc::flags.</li> +<li>Unified heightfields are now the default heightfield collision approach. This approach mirrors the way in which mesh contact gen functions so permits meshes and heightfields to be used interchangeably with negligible behavioral difference. The legacy heightfield collision approach can be used by calling PxRegisterLegacyHeightFields().</li> +<li>When unified heightfields are in use, the bounds of heightfield shapes will not be extruded by "thickness". If legacy heightfield collision is used, the bounds will still be extruded by thickness.</li> +</ul> +</div> +<div class="section" id="physx-cooking"> +<h2>PhysX Cooking<a class="headerlink" href="#physx-cooking" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>The deprecated flags PxMeshPreprocessingFlag::eREMOVE_UNREFERENCED_VERTICES and ::eREMOVE_DUPLICATED_TRIANGLES have been removed. Meshes get cleaned up by default unless PxMeshPreprocessingFlag::eDISABLE_CLEAN_MESH is set.</li> +<li>PxCookingParams::meshSizePerformanceTradeOff and PxCookingParams::meshCookingHint have been moved to PxBVH33MidphaseDesc, since they only affect the BVH33.</li> +<li>The PxGaussMapLimit.h file has been removed. The PxGetGaussMapVertexLimitForPlatform function has been moved to PxCooking.h, but the function is now deprecated, along with the PxPlatform enum. Instead there is now an explicit PxCookingParams::gaussMapLimit parameter. As far as transition to PhysX 3.4 is concerned there is nothing to do other than removing includes of PxGaussMapLimit.h, and perhaps including PxCooking.h instead if needed.</li> +<li>Legacy convex hull generator (PxConvexMeshCookingType::eINFLATION_INCREMENTAL_HULL) uses inflation in all cases. To cook a convex mesh without inflation new (default) PxConvexMeshCookingType::eQUICKHULL algorithm must be used. This algorithm does not support inflation.</li> +</ul> +</div> +<div class="section" id="reference-counting"> +<h2>Reference Counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>In previous releases, isReleasable() for shareable objects (shapes, triangle meshes, convex meshes, cloth fabrics, materials and heightfields) would return false once release() had been called on the object, which was only allowed once. In 3.4, reference counts can be manually incremented with acquireReference() and decremented with release(), and so the fact that release() has called once is not a reliable indicator of whether it can be called again.</li> +<li>As a consequence of the above, applications must ensure they own at least one counted reference to each shareable object in a collection before calling PxCollectionExt::releaseObjects. The main case in which this might be different in 3.4 is when using PxRigidActor::createShape(), since in that case only the actor has a counted reference to the shape. In this specific case, the new parameter releaseExclusiveShapes to PxCollectionExt::releaseObjects may be helpful.</li> +<li>Since there is no unique user release for shareable objects, they do not generate USER_RELEASE events when release() is called.</li> +</ul> +</div> +<div class="section" id="physx-visual-debugger"> +<h2>PhysX Visual Debugger<a class="headerlink" href="#physx-visual-debugger" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>PxVisualDebugger is deprecated, and new PxPvd has been introduced. More details are mentioned in <a class="reference internal" href="VisualDebugger.html#physxvisualdebugger"><em>PhysX Visual Debugger (PVD)</em></a>.</li> +</ul> +</div> +<div class="section" id="scene-queries"> +<h2>Scene queries<a class="headerlink" href="#scene-queries" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>PxPruningStructure enum has been renamed to PxPruningStructureType</li> +<li>Deprecated type PxSceneQueryHit has been removed. Please use PxQueryHit instead.</li> +<li>Deprecated type PxSceneQueryFilterData has been removed. Please use PxQueryFilterData instead.</li> +<li>Deprecated type PxSceneQueryFilterCallback has been removed. Please use PxQueryFilterCallback instead.</li> +<li>Deprecated type PxSceneQueryCache has been removed. Please use PxQueryCache instead.</li> +<li>Deprecated types PxSceneQueryFlag(s) has been removed. Please use PxHitFlag(s) instead.</li> +<li>Deprecated scene query functions have been removed (e.g. PxScene::raycastAny(), etc). To make the transition easier they are still available in PxSceneQueryExt.h, as part of PhysXExtensions. A previous PxScene::raycastAny(...) call should now either use PxSceneQueryExt::raycastAny(PxScene, ...), or PxScene::raycast(...).</li> +<li>PxHitFlag::eFACE_INDEX was introduced. In order to receive the face index in sweeps against convex geometry, the flag needs to be set.</li> +<li>PxHitFlag::eDISTANCE has been deprecated, since the distance is always needed and its computation cannot be skipped. Please simply avoid using that flag from now on. The flag has no effect and it will be removed in the next version.</li> +<li>The "anyHit" parameter of the PxGeometryQuery::raycast() and PxShapeExt::raycast() functions has been removed. Please use PxHitFlag::eMESH_ANY instead.</li> +<li>PxMeshQuery::sweep() now respects PxHitFlag::eMESH_BOTH_SIDES. So if you previously used that flag when calling that function, it was ignored, and the upgrade to 3.4 might start generating different results compared to 3.3. If keeping the previous behaviour is important, please disable PxHitFlag::eMESH_BOTH_SIDES in your PxMeshQuery::sweep() calls.</li> +<li>Batched scene queries are marked as deprecated and will be replaced by new system in future releases.</li> +<li>Volume cache feature is marked as deprecated, it will be removed in future releases.</li> +<li>Spatial index feature is marked as deprecated, it will be removed in future releases.</li> +</ul> +</div> +<div class="section" id="pxextensions"> +<h2>PxExtensions<a class="headerlink" href="#pxextensions" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>The signatures for the PxComputeMeshPenetration and PxComputeHeightFieldPenetration functions have changed. The old functions are still available but they are now deprecated. It is recommended to transition to the new functions (with the same names but a different signature).</li> +</ul> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Migrating From PhysX SDK 3.3 to 3.4</a><ul> +<li><a class="reference internal" href="#deprecated-apis">Deprecated APIs</a><ul> +<li><a class="reference internal" href="#pxrigidactor-createshape">PxRigidActor::createShape</a></li> +<li><a class="reference internal" href="#pxsceneflag-edeprecated-trigger-trigger-reports">PxSceneFlag::eDEPRECATED_TRIGGER_TRIGGER_REPORTS</a></li> +<li><a class="reference internal" href="#physx-particles">PhysX particles</a></li> +</ul> +</li> +<li><a class="reference internal" href="#core-physx">Core PhysX</a></li> +<li><a class="reference internal" href="#contact-generation">Contact Generation</a></li> +<li><a class="reference internal" href="#physx-cooking">PhysX Cooking</a></li> +<li><a class="reference internal" href="#reference-counting">Reference Counting</a></li> +<li><a class="reference internal" href="#physx-visual-debugger">PhysX Visual Debugger</a></li> +<li><a class="reference internal" href="#scene-queries">Scene queries</a></li> +<li><a class="reference internal" href="#pxextensions">PxExtensions</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="MigrationTo33.html" + title="previous chapter">Migrating From PhysX SDK 3.2 to 3.3</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" /> + <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="MigrationTo33.html" title="Migrating From PhysX SDK 3.2 to 3.3" + >previous</a></li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/OriginShift.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/OriginShift.html new file mode 100644 index 00000000..56d71e1b --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/OriginShift.html @@ -0,0 +1,121 @@ +<!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>Scene Origin — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="GPU Rigid Bodies" href="GPURigidBodies.html" /> + <link rel="prev" title="Articulations" href="Articulations.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="GPURigidBodies.html" title="GPU Rigid Bodies" + accesskey="N">next</a></li> + <li class="right" > + <a href="Articulations.html" title="Articulations" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="scene-origin"> +<span id="originshift"></span><h1>Scene Origin<a class="headerlink" href="#scene-origin" title="Permalink to this headline">¶</a></h1> +<p>The further away objects move from the origin, the larger the chance to suffer from floating point precision issues. This can cause troubles especially in scenarios with big game worlds. To avoid these problems, a straightforward solution seems to teleport all objects towards the origin in certain intervals. However, this is not only cumbersome but can also be pretty expensive due to the invalidation of cached data and persistent state. To address some of these issues, PhysX offers an API to shift the origin of a scene.</p> +<div class="section" id="shifting-the-scene-origin"> +<h2>Shifting The Scene Origin<a class="headerlink" href="#shifting-the-scene-origin" title="Permalink to this headline">¶</a></h2> +<p>The following method will shift the origin of a scene by a translation vector:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">::</span><span class="n">shiftOrigin</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">shift</span><span class="p">)</span> +</pre></div> +</div> +<p>The positions of all objects in the scene and the corresponding data structures will get adjusted to reflect the new origin location (basically, the shift vector will get subtracted from all object positions). The intended use pattern for this API is to shift the origin such that object positions move closer towards zero. Please note that it is the user's responsibility to keep track of the summed total origin shift and adjust all input/output to/from PhysX accordingly. +Even though this method preserves some of the internally cached data, it is still an expensive operation and we recommend to use it only in the case where distance related precision issues may arise in areas far from the origin. +If extension modules of PhysX are used like the character controller or vehicle library, then it will be necessary to propagate the scene shift to those modules as well. Please refer to the API documentation of these modules for details.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Scene Origin</a><ul> +<li><a class="reference internal" href="#shifting-the-scene-origin">Shifting The Scene Origin</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Articulations.html" + title="previous chapter">Articulations</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="GPURigidBodies.html" + title="next chapter">GPU Rigid Bodies</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" /> + <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="GPURigidBodies.html" title="GPU Rigid Bodies" + >next</a></li> + <li class="right" > + <a href="Articulations.html" title="Articulations" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Particles.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Particles.html new file mode 100644 index 00000000..f188627a --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Particles.html @@ -0,0 +1,566 @@ +<!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>Particles (deprecated) — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Cloth" href="Cloth.html" /> + <link rel="prev" title="Character Controllers" href="CharacterControllers.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Cloth.html" title="Cloth" + accesskey="N">next</a></li> + <li class="right" > + <a href="CharacterControllers.html" title="Character Controllers" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="particles-deprecated"> +<span id="particles"></span><h1>Particles (deprecated)<a class="headerlink" href="#particles-deprecated" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p><strong>The PhysX particle feature has been deprecated in PhysX version 3.4. The standalone library PhysX FleX is an alternative with a richer feature set.</strong></p> +<p>PhysX 3 offers two particle system types - a generic particle system and an SPH fluid particle system. The generic particle system provides basic particle motion and collision with rigid actors. It can be used for objects that require collisions against the environment, but for which inter-particle interactions are not needed. Examples include small debris, sparks or leaves. The SPH fluid particle system can be used for fluid effects that require approximate incompressibility and flowing behavior, such as liquids or fog and smoke filling up a volume.</p> +<p>PhysX 3 takes care of collision detection and particle dynamics, while auxiliary facilities such as emitters, +lifetime maintenance etc. need to be provided by the application.</p> +</div> +<div class="section" id="creating-particle-systems"> +<span id="creatingparticlesystem"></span><h2>Creating Particle Systems<a class="headerlink" href="#creating-particle-systems" title="Permalink to this headline">¶</a></h2> +<p>Both particle system classes <em>PxParticleSystem</em> and <em>PxParticleFluid</em> inherit from <em>PxParticleBase</em>, which is the +common interface providing particle manipulation and collision functionality. Particle systems inherit from <em>PxActor</em> +and can be added to a scene.</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/ParticleClassDiagram_1.png"><img alt="../_images/ParticleClassDiagram_1.png" src="../_images/ParticleClassDiagram_1.png" /></a> +<p class="caption">Figure 1: PxParticleSystem inherits all properties from PxParticleBase, PxParticleFluid adds fluid specific properties</p> +</div> +<p>The following section shows how a particle system is created and added:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// set immutable properties.</span> +<span class="n">PxU32</span> <span class="n">maxParticles</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">perParticleRestOffset</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span> + +<span class="c1">// create particle system in PhysX SDK</span> +<span class="n">PxParticleSystem</span><span class="o">*</span> <span class="n">ps</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-></span><span class="n">createParticleSystem</span><span class="p">(</span><span class="n">maxParticles</span><span class="p">,</span> <span class="n">perParticleRestOffset</span><span class="p">);</span> + +<span class="c1">// add particle system to scene, in case creation was successful</span> +<span class="k">if</span> <span class="p">(</span><span class="n">ps</span><span class="p">)</span> + <span class="n">mScene</span><span class="o">-></span><span class="n">addActor</span><span class="p">(</span><span class="o">*</span><span class="n">ps</span><span class="p">);</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The particle module has to be registered with <em>PxRegisterParticles</em> on platforms with static linking (non windows) before creating particle systems. <em>PxCreatePhysics</em> registers all modules by default as opposed to <em>PxCreateBasePhysics</em>.</p> +</div> +</div> +<div class="section" id="particle-management"> +<h2>Particle Management<a class="headerlink" href="#particle-management" title="Permalink to this headline">¶</a></h2> +<p>Particle systems reserve memory for a fixed number of particles - <em>PxParticleBase::getMaxParticles</em>. Each of these particles can be addressed with a fixed index throughout it's lifetime. The given range of indices is [0, <em>PxParticleBase::getMaxParticles</em>]. In order to support a dynamic amount of particles, particles are marked as being valid or invalid. This is achieved by two means: The valid particle range indicates the range within which particles may be valid. Outside that range all particles are defined as being invalid. Within that range valid particles are marked with the flag <em>PxParticleFlag::eVALID</em>. Alternatively PhysX provides a bitmap with each bit set corresponding to a valid particle within the valid particle range. The bitmap consists of an array of 32-bit unsigned integers with enough elements to cover the valid particle range.</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/ParticleValidScheme.png"><img alt="../_images/ParticleValidScheme.png" src="../_images/ParticleValidScheme.png" /></a> +<p class="caption">Figure 2: Scheme showing how valid particles are tracked</p> +</div> +<div class="section" id="creating-particles"> +<h3>Creating Particles<a class="headerlink" href="#creating-particles" title="Permalink to this headline">¶</a></h3> +<p>The application specifies an index for each new particle at particle creation time. If the application maintains its own representation of particles, and already tracks active indices, then these indices may be re-used by PhysX. If the application does not have appropriate indices at its disposal, it can use an index pool provided by the PhysX extensions library <em>PxParticleExt::IndexPool</em> as explained here: <a class="reference internal" href="#indexpool"><em>Index Pool Extension</em></a>.</p> +<p>PhysX 3 itself has no built-in emitters. Instead, it simply provides an interface to create particles with initial properties. When creating particles, specifying indices and positions is mandatory, while velocities and rest offsets may be specified optionally.</p> +<p>The PhysX particle API uses the PxStrideIterator template class to pass per particle data between the SDK and the application. This allows the particle data layout to be chosen more flexible by supporting interleaved arrays or padded data without forcing extra copies for reformatting. The stride iterator is configured by setting the type of the iterated data and specifying the pointer to the first element.</p> +<p>Example for creating a few particles:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// declare particle descriptor for creating new particles</span> +<span class="c1">// based on numNewAppParticles count and newAppParticleIndices,</span> +<span class="c1">// newAppParticlePositions arrays and newAppParticleVelocity</span> +<span class="n">PxParticleCreationData</span> <span class="n">particleCreationData</span><span class="p">;</span> +<span class="n">particleCreationData</span><span class="p">.</span><span class="n">numParticles</span> <span class="o">=</span> <span class="n">numNewAppParticles</span><span class="p">;</span> +<span class="n">particleCreationData</span><span class="p">.</span><span class="n">indexBuffer</span> <span class="o">=</span> <span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxU32</span><span class="o">></span><span class="p">(</span><span class="n">newAppParticleIndices</span><span class="p">);</span> +<span class="n">particleCreationData</span><span class="p">.</span><span class="n">positionBuffer</span> <span class="o">=</span> <span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">></span><span class="p">(</span><span class="n">newAppParticlePositions</span><span class="p">);</span> +<span class="n">particleCreationData</span><span class="p">.</span><span class="n">velocityBuffer</span> <span class="o">=</span> <span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">newAppParticleVelocity</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span> + +<span class="c1">// create particles in *PxParticleSystem* ps</span> +<span class="kt">bool</span> <span class="n">success</span> <span class="o">=</span> <span class="n">ps</span><span class="o">-></span><span class="n">createParticles</span><span class="p">(</span><span class="n">particleCreationData</span><span class="p">);</span> +</pre></div> +</div> +<p>The indices specified for particle creation need to be unique and within the limit of <em>PxParticleBase::getMaxParticles()</em>.</p> +<p>In this example the stride iterator is used to set the same velocity for all new particles. This is achieved by setting the stride to zero.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">For fluid particles it is necessary to spawn particles at distances close to <em>PxParticleFluid::getRestParticleDistance()</em> in order to achieve a regular emission, otherwise particles will spread immediately in all directions.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">In PhysX 3 all particle access such as creating, releasing, updating and reading particles can only be carried out while the simulation of the scene is not being executed.</p> +</div> +</div> +<div class="section" id="releasing-particles"> +<h3>Releasing Particles<a class="headerlink" href="#releasing-particles" title="Permalink to this headline">¶</a></h3> +<p>Particles can be released by providing indices to the particle system. As opposed to older versions of the PhysX SDK, particles get immediately released.</p> +<p>Example for releasing a few particles:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// declare strided iterator for providing array of indices corresponding to</span> +<span class="c1">// particles that should be removed</span> +<span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxU32</span><span class="o">></span> <span class="n">indexBuffer</span><span class="p">(</span><span class="n">appParticleIndices</span><span class="p">);</span> + +<span class="c1">// release particles in *PxParticleSystem* ps</span> +<span class="n">ps</span><span class="o">-></span><span class="n">releaseParticles</span><span class="p">(</span><span class="n">numAppParticleIndices</span><span class="p">,</span> <span class="n">indexBuffer</span><span class="p">);</span> +</pre></div> +</div> +<p>It is a requirement that the indices passed to the release method are unique and correspond to existing particles.</p> +<p>All particles can be released at once by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">ps</span><span class="o">-></span><span class="n">releaseParticles</span><span class="p">();</span> +</pre></div> +</div> +<p>Since only a limited number of particle slots <em>(PxParticleBase::getMaxParticles())</em> are available it might be appropriate to replace old particles with new ones. This can be achieved for instance by maintaining an application-side particle lifetime. There are other reasons to release particles:</p> +<ul class="simple"> +<li>Drains can be useful to remove particles that go to locations where they are not needed anymore. See <a class="reference internal" href="#particledrains"><em>Particle Drains</em></a>.</li> +<li>The spatial data structure used for particles may overflow. Particles that cannot be covered are marked and should be released. See <a class="reference internal" href="#particlegrid"><em>Particle Grid</em></a>.</li> +</ul> +</div> +<div class="section" id="index-pool-extension"> +<span id="indexpool"></span><h3>Index Pool Extension<a class="headerlink" href="#index-pool-extension" title="Permalink to this headline">¶</a></h3> +<p>Example for allocating particle indices using the PhysX extensions library:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// create an index pool for a particle system with maximum particle count of maxParticles</span> +<span class="n">PxParticleExt</span><span class="o">::</span><span class="n">IndexPool</span><span class="o">*</span> <span class="n">indexPool</span> <span class="o">=</span> <span class="n">PxParticleExt</span><span class="o">::</span><span class="n">createIndexPool</span><span class="p">(</span><span class="n">maxParticles</span><span class="p">);</span> + +<span class="c1">// use the indexPool for allocating numNewAppParticles indices that can be used</span> +<span class="c1">// for particle creation throughout the particle system lifetime. If numAllocated</span> +<span class="c1">// is smaller than numNewAppParticles, the maxParticles limit was exceeded</span> +<span class="n">PxU32</span> <span class="n">numAllocated</span> <span class="o">=</span> <span class="n">indexPool</span><span class="o">-></span><span class="n">allocateIndices</span><span class="p">(</span><span class="n">numNewAppParticles</span><span class="p">,</span> + <span class="n">PxStrideIterator</span><span class="o"><</span><span class="n">PxU32</span><span class="o">></span><span class="p">(</span><span class="n">newAppParticleIndices</span><span class="p">));</span> + +<span class="c1">// in order to reuse particle slots, the indices should be handed back to the</span> +<span class="c1">// indexPool after the particles have been released</span> +<span class="n">indexPool</span><span class="o">-></span><span class="n">freeIndices</span><span class="p">(</span><span class="n">numAppParticleIndices</span><span class="p">,</span> <span class="n">PxStrideIterator</span><span class="o"><</span><span class="n">PxU32</span><span class="o">></span><span class="p">(</span><span class="n">appParticleIndices</span><span class="p">));</span> + +<span class="c1">// if no further index management is needed, the pool should be released</span> +<span class="n">indexPool</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="updating-particles"> +<h3>Updating Particles<a class="headerlink" href="#updating-particles" title="Permalink to this headline">¶</a></h3> +<p>The following per-particle updates are carried out immediately:</p> +<ul class="simple"> +<li>Position updates: Teleporting particles from one location to another.</li> +<li>Velocity updates: Directly altering the velocities of particles.</li> +<li>Rest offset updates: Changes particle rest offsets (only available with <em>PxParticleBaseFlag::ePER_PARTICLE_REST_OFFSET</em>).</li> +</ul> +<p>Particle updates that are carried out during the next scene simulation step:</p> +<ul class="simple"> +<li>Force updates: Results in a velocity change update according to a vector unit specified by <em>PxForceMode</em>.</li> +</ul> +<p>Example for force update:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// specify strided iterator to provide update forces</span> +<span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">></span> <span class="n">forceBuffer</span><span class="p">(</span><span class="n">appParticleForces</span><span class="p">);</span> + +<span class="c1">// specify strided iterator to provide indices of particles that need to be updated</span> +<span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxU32</span><span class="o">></span> <span class="n">indexBuffer</span><span class="p">(</span><span class="n">appParticleForceIndices</span><span class="p">);</span> + +<span class="c1">// specify force update on PxParticleSystem ps choosing the "force" unit</span> +<span class="n">ps</span><span class="o">-></span><span class="n">addForces</span><span class="p">(</span><span class="n">numAppParticleForces</span><span class="p">,</span> <span class="n">indexBuffer</span><span class="p">,</span> <span class="n">forceBuffer</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">eFORCE</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="reading-particles"> +<span id="readingparticles"></span><h3>Reading Particles<a class="headerlink" href="#reading-particles" title="Permalink to this headline">¶</a></h3> +<p>The PhysX SDK does not provide to the user all simulated per-particle properties of a particle system by default. The application can specify the data it needs by configuring +PxParticleBase::particleReadDataFlags:</p> +<ul class="simple"> +<li><em>PxParticleReadDataFlag::ePOSITION_BUFFER:</em> On by default.</li> +<li><em>PxParticleReadDataFlag::eFLAGS_BUFFER:</em> On by default.</li> +<li><em>PxParticleReadDataFlag::eVELOCITY_BUFFER:</em> Off by default.</li> +<li><em>PxParticleReadDataFlag::eREST_OFFSET_BUFFER:</em> Off by default. May only be enabled if the particle system was created with per particle rest offset support. See <a class="reference internal" href="#creatingparticlesystem"><em>Creating Particle Systems</em></a>.</li> +<li><em>PxParticleReadDataFlag::eCOLLISION_NORMAL_BUFFER:</em> Off by default.</li> +<li><em>PxParticleReadDataFlag::eDENSITY_BUFFER:</em> Only available for particle fluids and off by default.</li> +</ul> +<p>Particle flags provide more information on individual particles:</p> +<ul class="simple"> +<li><em>PxParticleFlag::eVALID:</em> If set, the particle was created beforehand and not yet released. If not set, the particle slot does not contain a valid particle. All other properties are invalid in this case and should be ignored.</li> +<li><em>PxParticleFlag::eCOLLISION_WITH_STATIC:</em> Shows whether a particle collided with a rigid static during the last simulation step.</li> +<li><em>PxParticleFlag::eCOLLISION_WITH_DYNAMIC:</em> Shows whether a particle collided with a dynamic rigid body during the last simulation step.</li> +<li><em>PxParticleFlag::eCOLLISION_WITH_DRAIN:</em> Shows whether a particle collided with a rigid actor shape that was marked as a drain (<a class="reference internal" href="#particledrains"><em>Particle Drains</em></a>).</li> +<li><em>PxParticleFlag::eSPATIAL_DATA_STRUCTURE_OVERFLOW:</em> Shows whether a particle had to be omitted when building the SDK internal spatial data structure (<a class="reference internal" href="#particlegrid"><em>Particle Grid</em></a>).</li> +</ul> +<p>Particle collision normals represent contact normals between particles and rigid actor surfaces. A non-colliding particle has +a zero collision normal. Collision normals are useful e.g. for orienting the particle visualization according to their contact with rigid actors.</p> +<p>Particle densities provided by particle fluids can be used for rendering. A particle density has a value of zero for a particle that is +completely isolated. It has a value of one for a particle that has a particle neighborhood with a mean spacing corresponding to <em>PxParticleFluid::getRestParticleDistance()</em>.</p> +<p>Particle data can only be read while the scene simulation is not executing. In order to get access to the SDK buffers a <em>PxParticleReadData</em> instance needs to be acquired +from the SDK. It has the following properties:</p> +<ul class="simple"> +<li><em>numValidParticles:</em> Total number of valid particles for the corresponding particle system.</li> +<li><em>validParticleRange:</em> The index range of valid particles in the particle buffers.</li> +<li><em>validParticleBitmap:</em> Bitmap of valid particle locations.</li> +<li><em>positionBuffer, positionBuffer, velocityBuffer, restOffsetBuffer, flagsBuffer, collisionNormalBuffer:</em> Strided iterators for particle properties.</li> +</ul> +<p>Additionally particle fluids provide <em>PxParticleFluidReadData</em> with</p> +<ul class="simple"> +<li><em>densityBuffer:</em> Strided iterator for particle densities.</li> +</ul> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/ParticleClassDiagram_2.png"><img alt="../_images/ParticleClassDiagram_2.png" src="../_images/ParticleClassDiagram_2.png" /></a> +<p class="caption">Figure 3: PxParticleReadData and PxParticleFluidReadData</p> +</div> +<p>Example of how to access particle data:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// lock SDK buffers of *PxParticleSystem* ps for reading</span> +<span class="n">PxParticleReadData</span><span class="o">*</span> <span class="n">rd</span> <span class="o">=</span> <span class="n">ps</span><span class="o">-></span><span class="n">lockParticleReadData</span><span class="p">();</span> + +<span class="c1">// access particle data from PxParticleReadData</span> +<span class="k">if</span> <span class="p">(</span><span class="n">rd</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxParticleFlags</span><span class="o">></span> <span class="n">flagsIt</span><span class="p">(</span><span class="n">rd</span><span class="o">-></span><span class="n">flagsBuffer</span><span class="p">);</span> + <span class="n">PxStrideIterator</span><span class="o"><</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">></span> <span class="n">positionIt</span><span class="p">(</span><span class="n">rd</span><span class="o">-></span><span class="n">positionBuffer</span><span class="p">);</span> + + <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</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">rd</span><span class="o">-></span><span class="n">validParticleRange</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">,</span> <span class="o">++</span><span class="n">flagsIt</span><span class="p">,</span> <span class="o">++</span><span class="n">positionIt</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">if</span> <span class="p">(</span><span class="o">*</span><span class="n">flagsIt</span> <span class="o">&</span> <span class="n">PxParticleFlag</span><span class="o">::</span><span class="n">eVALID</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// access particle position</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">position</span> <span class="o">=</span> <span class="o">*</span><span class="n">positionIt</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> + + <span class="c1">// return ownership of the buffers back to the SDK</span> + <span class="n">rd</span><span class="o">-></span><span class="n">unlock</span><span class="p">();</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Example of how to use the valid particle bitmap to access particle data (without showing the locking and unlocking):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">rd</span><span class="o">-></span><span class="n">validParticleRange</span> <span class="o">></span> <span class="mi">0</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">// iterate over valid particle bitmap</span> + <span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">w</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">w</span> <span class="o"><=</span> <span class="p">(</span><span class="n">rd</span><span class="o">-></span><span class="n">validParticleRange</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">>></span> <span class="mi">5</span><span class="p">;</span> <span class="n">w</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">for</span> <span class="p">(</span><span class="n">PxU32</span> <span class="n">b</span> <span class="o">=</span> <span class="n">rd</span><span class="o">-></span><span class="n">validParticleBitmap</span><span class="p">[</span><span class="n">w</span><span class="p">];</span> <span class="n">b</span><span class="p">;</span> <span class="n">b</span> <span class="o">&=</span> <span class="n">b</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">PxU32</span> <span class="n">index</span> <span class="o">=</span> <span class="p">(</span><span class="n">w</span> <span class="o"><<</span> <span class="mi">5</span> <span class="o">|</span> <span class="n">Ps</span><span class="o">::</span><span class="n">lowestSetBit</span><span class="p">(</span><span class="n">b</span><span class="p">));</span> + + <span class="c1">// access particle position</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">position</span> <span class="o">=</span> <span class="n">rd</span><span class="o">-></span><span class="n">positionBuffer</span><span class="p">[</span><span class="n">index</span><span class="p">];</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="parameter-guide"> +<h2>Parameter Guide<a class="headerlink" href="#parameter-guide" title="Permalink to this headline">¶</a></h2> +<p>There are three types of particle system parameter. Some need to be specified when the particle system is created and cannot be changed afterwards. Some are mutable while the particle system is not part of a scene and others can be changed at any time. The following description covers parameter that either cannot be set at any time, or may induce a performance overhead when changed.</p> +<p><em>maxParticles:</em></p> +<blockquote> +<div>The maximum number of particles that can be added to a particle system. The smaller the value, the smaller the memory footprint of the particle system is going to be. Can only be set on particle system creation.</div></blockquote> +<p><em>PxParticleReadDataFlags:</em></p> +<blockquote> +<div>Specifies a subset of simulation properties which are returned to the application after simulation. See <a class="reference internal" href="#readingparticles"><em>Reading Particles</em></a>. As few read data flags should be set as possible in order to save memory and improve performance by avoiding unnecessary particle data copying. Parameter can only be changed while particle system is not part of a scene.</div></blockquote> +<p><em>gridSize:</em></p> +<blockquote> +<div>A hint for the PhysX SDK to choose the particle grouping granularity for proximity tests and parallelization. See <a class="reference internal" href="#particlegrid"><em>Particle Grid</em></a>. Parameter can only be changed while particle system is not part of a scene.</div></blockquote> +<p><em>PxParticleBaseFlag::eENABLED:</em></p> +<blockquote> +<div>Enables/disables particle simulation.</div></blockquote> +<p><em>PxParticleBaseFlag::eGPU:</em></p> +<blockquote> +<div>Enable/disable GPU acceleration. Changing this parameter while the particle system is part of a scene induces a large performance overhead.</div></blockquote> +<p><em>PxParticleBaseFlag::eCOLLISION_WITH_DYNAMIC_ACTORS:</em></p> +<blockquote> +<div>Enable/disable collision with dynamic rigids. Changing this parameter while the particle system is part of a scene induces a performance overhead.</div></blockquote> +<p><em>PxParticleBaseFlag::eCOLLISION_TWOWAY:</em></p> +<blockquote> +<div>Enable/disable twoway interaction between particles and rigid bodies. Changing this parameter while the particle system is part of a scene induces a performance overhead.</div></blockquote> +<p><em>PxParticleBaseFlag::ePER_PARTICLE_COLLISION_CACHE_HINT:</em></p> +<blockquote> +<div>Enable/disable internal collision caches. Changing this parameter while the particle system is part of a scene induces a performance overhead.</div></blockquote> +<div class="section" id="particle-dynamics"> +<h3>Particle Dynamics<a class="headerlink" href="#particle-dynamics" title="Permalink to this headline">¶</a></h3> +<p><em>externalAcceleration:</em></p> +<blockquote> +<div>Acceleration applied to each particle at each time step. The scene gravity which is added to the external acceleration by default can be disabled using <em>PxActorFlag::eDISABLE_GRAVITY</em>.</div></blockquote> +<p><em>maxMotionDistance:</em></p> +<blockquote> +<div>The maximum distance a particle can travel during one simulation step. High values may hurt performance, while low values may restrict the particle velocity too much. In order to improve performance it's advisable to set this to a low value and then increase it until particles can move fast enough to achieve the target effect. Parameter can only be changed while particle system is not part of a scene.</div></blockquote> +<p><em>damping:</em></p> +<blockquote> +<div>Velocity damping constant, which is globally applied to each particle. This is particularly useful when using particles for smoke to prevent ballistic behavior of individual particles which can look odd.</div></blockquote> +<p><em>particleMass:</em></p> +<blockquote> +<div>Mass used for two way interaction with rigid bodies (<em>PxParticleBaseFlag::eCOLLISION_TWOWAY</em>) and different force modes in the context of <em>PxParticleBase::addForces</em>. This mass property doesn't have any impact on the fluid dynamics simulation.</div></blockquote> +<p><em>PxParticleBaseFlag::ePROJECT_TO_PLANE, projectionPlaneNormal, projectionPlaneDistance:</em></p> +<blockquote> +<div>Parameter to configure the projection mode which confines particles to a plane. If projection is enabled particles can only move in a plane. This can be a useful option in the context of a 2D-Game.</div></blockquote> +</div> +<div class="section" id="collision-with-rigid-actors"> +<h3>Collision with Rigid Actors<a class="headerlink" href="#collision-with-rigid-actors" title="Permalink to this headline">¶</a></h3> +<p><em>restOffset:</em></p> +<blockquote> +<div>Defines the minimum distance between particles and the surface of rigid actors that is maintained by the collision system. Parameter can only be changed while particle system is not part of a scene.</div></blockquote> +<p><em>PxParticleBaseFlag::ePER_PARTICLE_REST_OFFSET:</em></p> +<blockquote> +<div>Enables/disables per-particle rest offsets. Memory can be saved by turning per particle rest offsets off. Per-particle rest offsets should only be enabled if the particles represent objects of significantly varying size, for example in the context of debris effects. See <a class="reference internal" href="#perparticlerestoffsets"><em>Per-particle Rest Offsets</em></a>. Can only be set on particle system creation.</div></blockquote> +<p><em>contactOffset:</em></p> +<blockquote> +<div>Defines the distance at which contacts between particles and rigid actors are created. The contacts are internally used to avoid jitter and sticking. It needs to be larger than <em>restOffset</em>. A good value to start with is about twice the size of the rest offset. Parameter can only be changed while particle system is not part of a scene.</div></blockquote> +<p><em>restitution:</em></p> +<blockquote> +<div>Restitution used for particle collision. This parameter defines how strongly particles bounce of rigid actors.</div></blockquote> +<p><em>dynamicFriction:</em></p> +<blockquote> +<div>Dynamic friction used for particle collision. This parameter defines how easily particles slide over rigid actor surfaces. The lower the value is to 0, the easier particles slide. One is the maximal value supported.</div></blockquote> +<p><em>staticFriction:</em></p> +<blockquote> +<div>Static friction used for particle collision. This parameter is similar to dynamic friction but defines how easily particles start to slide over a surface. Values larger than one are supported.</div></blockquote> +<p><em>simulationFilterData:</em></p> +<blockquote> +<div>Filter data used to filter collisions between particles and rigid bodies. See <a class="reference internal" href="#particlecollisionfiltering"><em>Collision Filtering</em></a>.</div></blockquote> +<p><em>PxParticleBaseFlag::eCOLLISION_TWOWAY:</em></p> +<blockquote> +<div>The collision two-way flag allows enabling/disabling two-way interaction between rigid bodies and particles. The particle mass parameter defines the strength of the interaction. The flag can only be changed while the particle system is not part of a scene.</div></blockquote> +</div> +<div class="section" id="fluid-pxparticlefluid"> +<h3>Fluid (PxParticleFluid)<a class="headerlink" href="#fluid-pxparticlefluid" title="Permalink to this headline">¶</a></h3> +<p>The SPH simulation can be tricky to tweak for good results. As this simulation technique (see <a class="reference internal" href="#particlereferences"><em>References</em></a>) uses an explicit integration scheme it only provides stable results within a certain parameter sub-space. A good set of parameter values depend on the time step size of the simulation and the external forces applied (such as gravity). The suggested starting points for parameter values below assume a time step size of about 1/60 [s] and a gravity around 10 [m/s^2]. Using a <em>damping</em> value larger than zero allows for a larger parameter sub-space, for example useful when implementing a smoke effect.</p> +<p><em>restParticleDistance:</em></p> +<blockquote> +<div>Defines the resolution of the particle fluid. It defines the approximate distance that neighboring particles will adopt within a fluid volume at rest. For the parameter tweaking assumption mentioned above, the particle rest distance should not be smaller than 0.05 [m]. Parameter can only be changed while particle system is not part of a scene.</div></blockquote> +<p><em>stiffness:</em></p> +<blockquote> +<div>The stiffness (or gas constant) influences the calculation of the pressure force field. Low values of stiffness make the fluid more compressible (i.e., springy), while high values make it less compressible. The stiffness value has a significant impact on the numerical stability of the simulation; setting very high values will result in instability. Reasonable values are usually between 1 and 200.</div></blockquote> +<p><em>viscosity:</em></p> +<blockquote> +<div>Viscosity controls a fluid's thickness. For example, a fluid with a high viscosity will behave like treacle, while a fluid with low viscosity will be more like water. The viscosity value scales the force to reduce the relative velocity of particles within the fluid. Both, too high and too low values will typically result in instabilities. Reasonable values are usually between 5 and 300.</div></blockquote> +</div> +</div> +<div class="section" id="collision-handling"> +<h2>Collision Handling<a class="headerlink" href="#collision-handling" title="Permalink to this headline">¶</a></h2> +<p>By default, particles will collide with any shapes inside the PxScene that they belong to. They will attempt to maintain a fixed distance from these shapes as specified by <em>PxParticleBase::setRestOffset()</em>.</p> +<div class="section" id="collision-filtering"> +<span id="particlecollisionfiltering"></span><h3>Collision Filtering<a class="headerlink" href="#collision-filtering" title="Permalink to this headline">¶</a></h3> +<p>Filtering particle versus rigid body collisions can be useful to avoid unnecessary performance overhead or simply to avoid undesired collisions.</p> +<p>For the following examples filtering is useful:</p> +<ul class="simple"> +<li>Avoid particles colliding with trigger shapes (this is already the behavior of <em>PxDefaultSimulationFilterShader</em>)</li> +<li>Configure a drain shape to exclusively collide with particles</li> +<li>Have particles collide with a proxy shape as opposed to the shape used for rigid body collisions</li> +</ul> +<p>Filter information for particles can be specified by calling <em>PxParticleBase::setSimulationFilterData()</em>. Instructions for how to setup filter shaders can be found here: <a class="reference internal" href="RigidBodyCollision.html#collisionfiltering"><em>Collision Filtering</em></a>.</p> +</div> +<div class="section" id="per-particle-rest-offsets"> +<span id="perparticlerestoffsets"></span><h3>Per-particle Rest Offsets<a class="headerlink" href="#per-particle-rest-offsets" title="Permalink to this headline">¶</a></h3> +<p>It is also possible to set a rest offset per-particle, using <em>PxParticleBase::setRestOffsets()</em>. In order to provide per-particle rest offsets <em>PxParticleBaseFlag::ePER_PARTICLE_REST_OFFSET</em> needs to be set and the rest offsets must be smaller than the per-system value given by <em>PxParticleBase.getRestOffset()</em>.</p> +</div> +<div class="section" id="particle-drains"> +<span id="particledrains"></span><h3>Particle Drains<a class="headerlink" href="#particle-drains" title="Permalink to this headline">¶</a></h3> +<p>Using drains is a good method for keeping the particle count and spread under control. Placing drains around the area of interest in which a particle system is used helps to maintain good performance of the particle simulation. The area of interest could, for example, also be moved with the player.</p> +<p>Example of how to flag a <em>PxShape</em> rbShape as a drain:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">rbShape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">ePARTICLE_DRAIN</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Particles that collide with a drain are marked with <em>PxParticleFlag::eCOLLISION_WITH_DRAIN</em> and may be released.</p> +</div> +</div> +<div class="section" id="best-practices-troubleshooting"> +<h2>Best Practices / Troubleshooting<a class="headerlink" href="#best-practices-troubleshooting" title="Permalink to this headline">¶</a></h2> +<div class="section" id="particle-grid-and-spatial-data-structure-overflow"> +<span id="particlegrid"></span><h3>Particle Grid and Spatial Data Structure Overflow<a class="headerlink" href="#particle-grid-and-spatial-data-structure-overflow" title="Permalink to this headline">¶</a></h3> +<p>The PhysX SDK uses a grid to subdivide the particles of a particle system into spatial groups. This is done to accelerate proximity queries and for parallelization purposes. The grid size parameter needs to be experimentally adjusted with <em>PxParticleBase::setGridSize()</em> for best performance. When doing this it is helpful to visualize the grid using <em>PxVisualizationParameter::ePARTICLE_SYSTEM_GRID</em>. Small grid size values might result in spatial data structure overflow, since the number of grid cells is limited to about 1000. Large grid size values on the other hand might result in poor performance due to ineffective spatial queries or lack of parallelization opportunities.</p> +<p>In case of overflow, some particles will stop colliding with rigid actors in the scene. These particles are marked with +<em>PxParticleFlag::eSPATIAL_DATA_STRUCTURE_OVERFLOW</em> and should be released.</p> +</div> +</div> +<div class="section" id="gpu-cuda-acceleration"> +<h2>GPU/CUDA Acceleration<a class="headerlink" href="#gpu-cuda-acceleration" title="Permalink to this headline">¶</a></h2> +<p>PhysX 3 supports GPU acceleration. This allows for larger and more detailed particle effects while retaining good performance levels. To achieve this gain we must use a <em>physx::PxGpuDispatcher</em> for the scene we want to add the particle system to:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if PX_WINDOWS</span> + <span class="c1">// create cuda context manager</span> + <span class="n">PxFoundation</span><span class="o">&</span> <span class="n">foundation</span> <span class="o">=</span> <span class="p">...</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxCudaContextManagerDesc</span> <span class="n">cudaContextManagerDesc</span><span class="p">;</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxCudaContextManager</span><span class="o">*</span> <span class="n">cudaContextManager</span> <span class="o">=</span> + <span class="n">PxCreateCudaContextManager</span><span class="p">(</span><span class="n">foundation</span><span class="p">,</span> <span class="n">cudaContextManagerDesc</span><span class="p">)</span> +<span class="cp">#endif</span> + + <span class="n">PxSceneDesc</span> <span class="n">sceneDesc</span><span class="p">(</span><span class="n">mPhysics</span><span class="o">-></span><span class="n">getTolerancesScale</span><span class="p">());</span> + <span class="c1">//...</span> +<span class="cp">#if PX_WINDOWS</span> + <span class="k">if</span> <span class="p">(</span><span class="n">cudaContextManager</span><span class="p">)</span> + <span class="n">sceneDesc</span><span class="p">.</span><span class="n">gpuDispatcher</span> <span class="o">=</span> <span class="n">cudaContextManager</span><span class="o">-></span><span class="n">getGpuDispatcher</span><span class="p">();</span> +<span class="cp">#endif</span> + <span class="c1">//...</span> + <span class="n">physicsSdk</span><span class="o">-></span><span class="n">createScene</span><span class="p">(</span><span class="n">sceneDesc</span><span class="p">);</span> +</pre></div> +</div> +<p>A particle system can be configured for GPU simulation by setting <em>PxParticleBaseFlag::eGPU</em>. Toggling GPU acceleration while the particle system is part of a scene might have a bad impact on performance since its state needs to be copied to or from the GPU device memory. It is therefore better to set the flag with <em>PxParticleBase::setParticleBaseFlag()</em> before adding the particle system to the scene.</p> +<p>Particle data can be read directly from the GPU device using <em>PxParticleBase::lockParticleReadData(PxDataAccessFlag::eDEVICE)</em> and <em>PxParticleFluid::lockParticleFluidReadData(PxDataAccessFlag::eDEVICE)</em>. This can be used to render particles directly with CUDA Graphics Interop.</p> +<p>Convex, Triangle and Height field meshes are automatically mirrored in the GPU memory when the corresponding shapes are within the proximity of a GPU accelerated particle system. This may cause some undesired performance hiccups which can be prevented by mirroring the meshes explicitly, as shown in this example:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if PX_WINDOWS</span> + <span class="c1">// mirror PxTriangleMesh triangleMesh providing the corresponding cudaContextManager of</span> + <span class="c1">// the desired scene.</span> + <span class="n">PxParticleGpu</span><span class="o">::</span><span class="n">createTriangleMeshMirror</span><span class="p">(</span><span class="n">triangleMesh</span><span class="p">,</span> <span class="o">*</span><span class="n">cudaContextManager</span><span class="p">);</span> + + <span class="c1">// later release the obsolete mirror</span> + <span class="n">PxParticleGpu</span><span class="o">::</span><span class="n">releaseTriangleMeshMirror</span><span class="p">(</span><span class="n">triangleMesh</span><span class="p">,</span> <span class="o">*</span><span class="n">cudaContextManager</span><span class="p">);</span> +<span class="cp">#endif</span> +</pre></div> +</div> +<p>On Kepler and above GPUs, the triangle meshes can be cached to achieve better performance. The amount of memory to be allocated for caching can be set using:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxParticleGpu</span><span class="o">::</span><span class="n">setTriangleMeshCacheSizeHint</span><span class="p">(</span><span class="k">const</span> <span class="k">class</span> <span class="nc">PxScene</span><span class="o">&</span> <span class="n">scene</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">size</span><span class="p">);</span> +</pre></div> +</div> +<p>The triangle mesh cache will be shared among all the particle systems created in the scene. The optimal size depends on the scene (i.e. triangle mesh density and particle distribution). +The cache usage statistics can be queried and analyzed to fine tune the cache size hint.</p> +</div> +<div class="section" id="sample-discussion"> +<h2>Sample Discussion<a class="headerlink" href="#sample-discussion" title="Permalink to this headline">¶</a></h2> +<p>The SampleParticles shows both particle system types being used: <em>PxParticleSystem</em> is used for small debris and smoke, while <em>PxParticleFluid</em> is used for a waterfall. The sample provides example implementations of various aspects described in this guide:</p> +<ul class="simple"> +<li><em>SampleParticles::createParticleSystem</em>, <em>SampleParticles::createFluid</em> show how to create particle systems.</li> +<li><em>ParticleSystem::createParticles</em> creates particles within a particle system.</li> +<li><em>ParticleSystem::update</em> shows how to read, update, release particles and how to deal with spatial data structure overflows.</li> +<li><em>SampleParticlesFilterShader</em> is an example for setting up collision filtering.</li> +<li><em>SampleParticles::createDrain</em> shows how to setup a rigid body shape as a particle drain.</li> +<li><em>SampleBase::onInit</em> illustrates how to setup GPU/CUDA acceleration.</li> +</ul> +<p>The sample makes use of various helper classes:</p> +<ul class="simple"> +<li><em>ParticleSystem:</em> Encapsulates a <em>PxParticleSystem</em> or <em>PxParticleFluid</em> instance and manages application side data such as particle lifetimes and orientations for debris. It facilitates creating and releasing particles and double buffers particle data for asynchronous rendering.</li> +<li><em>RenderParticleSystemActor:</em> Owns a <em>ParticleSystem</em> and provides rendering functionality.</li> +<li><em>ParticleEmitterRate:</em> Emits particles at a specified rate (#particles per second).</li> +<li><em>ParticleEmitterPressure:</em> Emits particles maintaining a certain distance between them.</li> +<li><em>SampleParticles::Emitter:</em> Connects an emitter as described above with a <em>RenderParticleSystemActor</em>.</li> +<li><em>SampleParticles::Raygun:</em> Provides functionality for the ray force field, rigid body debris, particle debris and smoke emission.</li> +</ul> +<p>In the sample, the smoke effect is achieved by using a <em>PxParticleSystem</em> without gravity. Each particle is rendered as a point sprite with a smoke texture. The sprites fade away when the particles get close to the end of their lifespan. The smoke particles collide with the scene, which can be seen when roaming the smoke with the ray-gun. Smoke is generated for the craters, as well as for the ray-gun impacts. The realism of the smoke effect could be increased by using a particle fluid in order to get the smoke volume to expand. This is typically useful for indoor scenes or ground fog like effects where the particles get into pooling situations.</p> +<p>Two kinds of debris are shown in the sample. Larger chunks of debris are represented using convex-shaped rigid bodies. Smaller but more abundant chunks are represented by particles, which helps performance. The particle based debris is rendered using instanced meshes. It is spawned in the craters and at the ray-gun impact location.</p> +<p>In order to give the chunks the appearance of a tumbling motion a simple trick is used.</p> +<ol class="arabic simple"> +<li>Assign an initial random rotation matrix to each particle.</li> +<li>Change this rotation matrix proportional to the linear velocity of particle.</li> +</ol> +<p>The implementation of this approach can be found in <em>ParticleSystem::initializeParticlesOrientations</em> and <em>ParticleSystem::modifyRotationMatrix</em>.</p> +</div> +<div class="section" id="references"> +<span id="particlereferences"></span><h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><em>Particle-Based Fluid Simulation for Interactive Applications</em></div> +<div class="line">Matthias Muller, David Charypar and Markus Gross, Eurogrpahics/Siggraph 2003, D. Breeen, M. Lin Editors</div> +<div class="line"><a class="reference external" href="http://www.matthiasmueller.info/publications/sca03.pdf">http://www.matthiasmueller.info/publications/sca03.pdf</a></div> +</div> +<div class="line-block"> +<div class="line"><em>Fast GPU Fluid Simulation in PhysX</em></div> +<div class="line">Simon Schirm and Mark Harris, NVIDIA Corporation</div> +<div class="line">Chapter 7.3 of Game Programming Gems 8, Adam Lake</div> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Particles (deprecated)</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#creating-particle-systems">Creating Particle Systems</a></li> +<li><a class="reference internal" href="#particle-management">Particle Management</a><ul> +<li><a class="reference internal" href="#creating-particles">Creating Particles</a></li> +<li><a class="reference internal" href="#releasing-particles">Releasing Particles</a></li> +<li><a class="reference internal" href="#index-pool-extension">Index Pool Extension</a></li> +<li><a class="reference internal" href="#updating-particles">Updating Particles</a></li> +<li><a class="reference internal" href="#reading-particles">Reading Particles</a></li> +</ul> +</li> +<li><a class="reference internal" href="#parameter-guide">Parameter Guide</a><ul> +<li><a class="reference internal" href="#particle-dynamics">Particle Dynamics</a></li> +<li><a class="reference internal" href="#collision-with-rigid-actors">Collision with Rigid Actors</a></li> +<li><a class="reference internal" href="#fluid-pxparticlefluid">Fluid (PxParticleFluid)</a></li> +</ul> +</li> +<li><a class="reference internal" href="#collision-handling">Collision Handling</a><ul> +<li><a class="reference internal" href="#collision-filtering">Collision Filtering</a></li> +<li><a class="reference internal" href="#per-particle-rest-offsets">Per-particle Rest Offsets</a></li> +<li><a class="reference internal" href="#particle-drains">Particle Drains</a></li> +</ul> +</li> +<li><a class="reference internal" href="#best-practices-troubleshooting">Best Practices / Troubleshooting</a><ul> +<li><a class="reference internal" href="#particle-grid-and-spatial-data-structure-overflow">Particle Grid and Spatial Data Structure Overflow</a></li> +</ul> +</li> +<li><a class="reference internal" href="#gpu-cuda-acceleration">GPU/CUDA Acceleration</a></li> +<li><a class="reference internal" href="#sample-discussion">Sample Discussion</a></li> +<li><a class="reference internal" href="#references">References</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="CharacterControllers.html" + title="previous chapter">Character Controllers</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Cloth.html" + title="next chapter">Cloth</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" /> + <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="Cloth.html" title="Cloth" + >next</a></li> + <li class="right" > + <a href="CharacterControllers.html" title="Character Controllers" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyCollision.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyCollision.html new file mode 100644 index 00000000..9d3aa2ca --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyCollision.html @@ -0,0 +1,458 @@ +<!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>Rigid Body Collision — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Rigid Body Dynamics" href="RigidBodyDynamics.html" /> + <link rel="prev" title="Rigid Body Overview" href="RigidBodyOverview.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="RigidBodyDynamics.html" title="Rigid Body Dynamics" + accesskey="N">next</a></li> + <li class="right" > + <a href="RigidBodyOverview.html" title="Rigid Body Overview" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="rigid-body-collision"> +<span id="rigidbodycollision"></span><h1>Rigid Body Collision<a class="headerlink" href="#rigid-body-collision" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This section will introduce the fundamentals of rigid body collision.</p> +</div> +<div class="section" id="shapes"> +<span id="rigidbodycollisionshapes"></span><h2>Shapes<a class="headerlink" href="#shapes" title="Permalink to this headline">¶</a></h2> +<p>Shapes describe the spatial extent and collision properties of actors. They are used for three purposes within PhysX: intersection tests that determine the contacting features of rigid objects, scene query tests such as raycasts, and defining trigger volumes that generate notifications when other shapes intersect with them.</p> +<p>Shapes are reference counted, see <a class="reference internal" href="API.html#basicreferencecounting"><em>Reference Counting</em></a>.</p> +<p>Each shape contains a PxGeometry object and a reference to a PxMaterial, which must both be specified upon creation. +The following code creates a shape with a sphere geometry and a specific material:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createShape</span><span class="p">(</span><span class="n">PxSphereGeometry</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">),</span> <span class="n">myMaterial</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +<span class="n">myActor</span><span class="p">.</span><span class="n">attachShape</span><span class="p">(</span><span class="o">*</span><span class="n">shape</span><span class="p">);</span> +<span class="n">shape</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>The method PxRigidActorExt::createExclusiveShape() is equivalent to the three lines above.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">for reference counting behavior of deserialized shapes refer to <a class="reference internal" href="Serialization.html#deserializereferencecounting"><em>Reference Counting of Deserialized Objects</em></a>.</p> +</div> +<p>The parameter 'true' to createShape() informs the SDK that the shape will not be shared with other actors. You can use shape sharing to reduce the memory costs of your simulation when you have many actors with identical geometry, but shared shapes have a very strong restriction: you cannot update the attributes of a shared shape while it is attached to an actor.</p> +<p>Optionally you may configure a shape by specifying shape flags of type PxShapeFlags. By default a shape is configured as</p> +<ul class="simple"> +<li>a simulation shape (enabled for contact generation during simulation)</li> +<li>a scene query shape (enabled for scene queries)</li> +<li>being visualized if debug rendering is enabled</li> +</ul> +<p>When a geometry object is specified for a shape, the geometry object is copied into the shape. There are some restrictions on which geometries may be specified for a shape, depending on the shape flags and the type of the parent actors.</p> +<ul class="simple"> +<li>TriangleMesh, HeightField and Plane geometries are not supported for simulation shapes that are attached to dynamic actors, unless the dynamic actors are configured to be kinematic.</li> +<li>TriangleMesh and HeightField geometries are not supported for trigger shapes.</li> +</ul> +<p>See the following sections for more details.</p> +<p>Detach the shape from the actor as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">myActor</span><span class="p">.</span><span class="n">detachShape</span><span class="p">(</span><span class="o">*</span><span class="n">shape</span><span class="p">);</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">in previous versions of PhysX, release() was used to detach a shape from its actor and destroy it. This use of release() is deprecated in PhysX 3.3 and will not be supported in futures version of PhysX.</p> +</div> +</div> +<div class="section" id="simulation-shapes-and-scene-query-shapes"> +<h2>Simulation Shapes and Scene Query Shapes<a class="headerlink" href="#simulation-shapes-and-scene-query-shapes" title="Permalink to this headline">¶</a></h2> +<p>Shapes may be independently configured to participate in either or both of scene queries and contact tests. By default, a shape will participate in both.</p> +<p>The following pseudo-code configures a PxShape instance so that it no longer participates in shape pair intersection tests:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">disableShapeInContactTests</span><span class="p">(</span><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">shape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">eSIMULATION_SHAPE</span><span class="p">,</span><span class="nb">false</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>A PxShape instance can be configured to participate in shape pair intersection tests as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">enableShapeInContactTests</span><span class="p">(</span><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">shape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">eSIMULATION_SHAPE</span><span class="p">,</span><span class="nb">true</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>To disable a PxShape instance from scene query tests:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">disableShapeInSceneQueryTests</span><span class="p">(</span><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">shape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">eSCENE_QUERY_SHAPE</span><span class="p">,</span><span class="nb">false</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Finally, a PxShape instance can be re-enabled in scene query tests:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">enableShapeInSceneQueryTests</span><span class="p">(</span><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">shape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">eSCENE_QUERY_SHAPE</span><span class="p">,</span><span class="nb">true</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">If the movement of the shape's actor does not need to be controlled by the simulation at all, i.e., the shape is used for scene queries only and gets moved manually if necessary, then memory can be saved by additionally disabling simulation on the actor (see the API documentation on PxActorFlag::eDISABLE_SIMULATION).</p> +</div> +</div> +<div class="section" id="kinematic-triangle-meshes-planes-heighfields"> +<h2>Kinematic Triangle Meshes (Planes, Heighfields)<a class="headerlink" href="#kinematic-triangle-meshes-planes-heighfields" title="Permalink to this headline">¶</a></h2> +<p>It is possible to create a kinematic PxRigidDynamic which can have a triangle mesh (plane, heighfield) shape. If this shape has a simulation shape flag, this actor must stay kinematic. If you change the flag to not simulated, you can switch even the kinematic flag.</p> +<p>To setup kinematic triangle mesh see following code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">meshActor</span> <span class="o">=</span> <span class="n">getPhysics</span><span class="p">().</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">));</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">meshShape</span><span class="p">;</span> +<span class="k">if</span><span class="p">(</span><span class="n">meshActor</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">meshActor</span><span class="o">-></span><span class="n">setRigidDynamicFlag</span><span class="p">(</span><span class="n">PxRigidDynamicFlag</span><span class="o">::</span><span class="n">eKINEMATIC</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + + <span class="n">PxTriangleMeshGeometry</span> <span class="n">triGeom</span><span class="p">;</span> + <span class="n">triGeom</span><span class="p">.</span><span class="n">triangleMesh</span> <span class="o">=</span> <span class="n">triangleMesh</span><span class="p">;</span> + <span class="n">meshShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">meshActor</span><span class="p">,</span><span class="n">triGeom</span><span class="p">,</span> + <span class="n">defaultMaterial</span><span class="p">);</span> + <span class="n">getScene</span><span class="p">().</span><span class="n">addActor</span><span class="p">(</span><span class="o">*</span><span class="n">meshActor</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>To switch a kinematic triangle mesh actor to a dynamic actor:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">meshActor</span> <span class="o">=</span> <span class="n">getPhysics</span><span class="p">().</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">));</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">meshShape</span><span class="p">;</span> +<span class="k">if</span><span class="p">(</span><span class="n">meshActor</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">meshActor</span><span class="o">-></span><span class="n">setRigidDynamicFlag</span><span class="p">(</span><span class="n">PxRigidDynamicFlag</span><span class="o">::</span><span class="n">eKINEMATIC</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + + <span class="n">PxTriangleMeshGeometry</span> <span class="n">triGeom</span><span class="p">;</span> + <span class="n">triGeom</span><span class="p">.</span><span class="n">triangleMesh</span> <span class="o">=</span> <span class="n">triangleMesh</span><span class="p">;</span> + <span class="n">meshShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">meshActor</span><span class="p">,</span> <span class="n">triGeom</span><span class="p">,</span> + <span class="n">defaultMaterial</span><span class="p">);</span> + <span class="n">getScene</span><span class="p">().</span><span class="n">addActor</span><span class="p">(</span><span class="o">*</span><span class="n">meshActor</span><span class="p">);</span> + + <span class="n">PxConvexMeshGeometry</span> <span class="n">convexGeom</span> <span class="o">=</span> <span class="n">PxConvexMeshGeometry</span><span class="p">(</span><span class="n">convexBox</span><span class="p">);</span> + <span class="n">convexShape</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">meshActor</span><span class="p">,</span> <span class="n">convexGeom</span><span class="p">,</span> + <span class="n">defaultMaterial</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="broad-phase-algorithms"> +<h2>Broad-phase Algorithms<a class="headerlink" href="#broad-phase-algorithms" title="Permalink to this headline">¶</a></h2> +<p>PhysX supports several broad-phase algorithms:</p> +<ul class="simple"> +<li><em>sweep-and-prune (SAP)</em></li> +<li><em>multi box pruning (MBP)</em></li> +</ul> +<p><em>PxBroadPhaseType::eSAP</em> was the default algorithm used until PhysX 3.2. It is a good generic choice with great performance when many objects are sleeping. Performance can degrade significantly though, when all objects are moving, or when large numbers of objects are added to or removed from the broad-phase. This algorithm does not need world bounds to be defined in order to work.</p> +<p><em>PxBroadPhaseType::eMBP</em> is a new algorithm introduced in PhysX 3.3. It is an alternative broad-phase algorithm that does not suffer from the same performance issues as eSAP when all objects are moving or when inserting large numbers of objects. However its generic performance when many objects are sleeping might be inferior to eSAP, and it requires users to define world bounds in order to work.</p> +<p>The desired broad-phase algorithm is controlled by the <em>PxBroadPhaseType</em> enum, within the <em>PxSceneDesc</em> structure.</p> +</div> +<div class="section" id="regions-of-interest"> +<h2>Regions of Interest<a class="headerlink" href="#regions-of-interest" title="Permalink to this headline">¶</a></h2> +<p>A region of interest is a world-space AABB around a volume of space controlled by the broad-phase. Objects contained inside those regions are properly handled by the broad-phase. Objects falling outside of those regions lose all collision detection. Ideally those regions should cover the whole game space, while limiting the amount of covered empty space.</p> +<p>Regions can overlap, although for maximum efficiency it is recommended to minimize the amount of overlap between regions as much as possible. Note that two regions whose AABBs just touch are not considered overlapping. For example the <em>PxBroadPhaseExt::createRegionsFromWorldBounds</em> helper function creates a number of non-overlapping region bounds by simply subdividing a given world AABB into a regular 2D grid.</p> +<p>Regions can be defined by the <em>PxBroadPhaseRegion</em> structure, along with a user-data assigned to them. They can be defined at scene creation time or at runtime using the <em>PxScene::addBroadPhaseRegion</em> function. The SDK returns handles assigned to the newly created regions, that can be used later to remove regions using the <em>PxScene::removeBroadPhaseRegion</em> function.</p> +<p>A newly added region may overlap already existing objects. The SDK can automatically add those objects to the new region, if the <em>populateRegion</em> parameter from the <em>PxScene::addBroadPhaseRegion</em> call is set. However this operation is not cheap and might have a high impact on performance, especially when several regions are added in the same frame. Thus, it is recommended to disable it whenever possible. The region would then be created empty, and it would only be populated either with objects added to the scene after the region has been created, or with previously existing objects when they are updated (i.e. when they move).</p> +<p>Note that only <em>PxBroadPhaseType::eMBP</em> requires regions to be defined. The <em>PxBroadPhaseType::eSAP</em> algorithm does not. This information is captured within the <em>PxBroadPhaseCaps</em> structure, which lists information and capabilities of each broad-phase algorithm. This structure can be retrieved by the <em>PxScene::getBroadPhaseCaps</em> function.</p> +<p>Runtime information about current regions can be retrieved using the <em>PxScene::getNbBroadPhaseRegions</em> and <em>PxScene::getBroadPhaseRegions</em> functions.</p> +<p>The maximum number of regions is currently limited to 256.</p> +</div> +<div class="section" id="broad-phase-callback"> +<h2>Broad-phase Callback<a class="headerlink" href="#broad-phase-callback" title="Permalink to this headline">¶</a></h2> +<p>A callback for broad-phase-related events can be defined within the <em>PxSceneDesc</em> structure. This <em>PxBroadPhaseCallback</em> object will be called when objects are found out of the specified regions of interest, i.e. "out of bounds". The SDK disables collision detection for those objects. It is re-enabled automatically as soon as the objects re-enter a valid region.</p> +<p>It is up to users to decide what to do with out-of-bounds objects. Typical options are:</p> +<ul class="simple"> +<li>delete the objects</li> +<li>let them continue their motion without collisions until they re-enter a valid region</li> +<li>artificially teleport them back to a valid place</li> +</ul> +</div> +<div class="section" id="collision-filtering"> +<span id="collisionfiltering"></span><h2>Collision Filtering<a class="headerlink" href="#collision-filtering" title="Permalink to this headline">¶</a></h2> +<p>In almost all applications beyond the trivial, the need arises to exempt certain pairs of objects from interacting, or to configure the SDK collision detection behavior in a particular way for an interacting pair. In the submarine sample, like indicated above, we need to be notified when the submarine touched a mine, or the chain of a mine, so that we can have them blow up. The crab's AI also needs to know when crabs touch the heightfield.</p> +<p>Before we can understand what the sample does to achieve this, we need to understand the possibilities of the SDK filtering system. Because filtering potentially interacting pairs happens in the deepest parts of the simulation engine, and needs to be applied to all pairs of objects that come near each other, it is particularly performance sensitive. The simplest way to implement it would be to always call a callback function to each potentially interacting pair, where the application, based on the two object pointers could determine, using some custom logic -- like consulting its game data base -- whether the pair should interact. Unfortunately this quickly becomes too slow if done for a very large game world, especially if the collision detection processing happens on a remote processor like the GPU or an other kind of vector processor with local memory, which would have to suspend its parallel computations, interrupt the main processor that runs game code, and have it execute the callback before it can continue. Even if it were to be executed on a CPU, it would likely be done so simultaneously on multiple cores or hyperthreads, and thread safe code would have to be put in place to make sure that concurrent access to shared data is safe. Far better is to use some kind of fixed function logic that can execute on the remote processor. This is what we did in PhysX 2.x -- unfortunately the simple group based filtering rules we provided were not flexible enough to cover all applications. In 3.0, we introduce both a shader system, which lets the developer implement an arbitrary system of rules using code that runs on the vector processor (and is therefore not able to access any eventual game data base in main memory), which is more flexible than 2.x fixed function filtering, but just as efficient, and a totally flexible callback mechanism where the filter shader calls a CPU callback function that is able to access any application data, at the cost of performance -- see PxSimulationFilterCallback for details. The best part is that an application can decide on a per-pair basis to make this speed vs. flexibility trade-off.</p> +<p>Let us look at the shader system first: Here is the filter shader implemented by SampleSubmarine:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxFilterFlags</span> <span class="nf">SampleSubmarineFilterShader</span><span class="p">(</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes0</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData0</span><span class="p">,</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes1</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData1</span><span class="p">,</span> + <span class="n">PxPairFlags</span><span class="o">&</span> <span class="n">pairFlags</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">constantBlockSize</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">// let triggers through</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxFilterObjectIsTrigger</span><span class="p">(</span><span class="n">attributes0</span><span class="p">)</span> <span class="o">||</span> <span class="n">PxFilterObjectIsTrigger</span><span class="p">(</span><span class="n">attributes1</span><span class="p">))</span> + <span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eTRIGGER_DEFAULT</span><span class="p">;</span> + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">;</span> + <span class="p">}</span> + <span class="c1">// generate contacts for all that were not filtered above</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eCONTACT_DEFAULT</span><span class="p">;</span> + + <span class="c1">// trigger the contact callback for pairs (A,B) where</span> + <span class="c1">// the filtermask of A contains the ID of B and vice versa.</span> + <span class="k">if</span><span class="p">((</span><span class="n">filterData0</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData1</span><span class="p">.</span><span class="n">word1</span><span class="p">)</span> <span class="o">&&</span> <span class="p">(</span><span class="n">filterData1</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData0</span><span class="p">.</span><span class="n">word1</span><span class="p">))</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eNOTIFY_TOUCH_FOUND</span><span class="p">;</span> + + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>SampleSubmarineFilterShader is a simple shader function that is an implementation of the PxSimulationFilterShader prototype declared in PxFiltering.h. The shader filter function (called SampleSubmarineFilterShader above) may not reference any memory other than arguments of the function and its own local stack variables -- because the function may be compiled and executed on a remote processor.</p> +<p>SampleSubmarineFilterShader() will be called for all pairs of shapes that come near each other -- more precisely: for all pairs of shapes whose axis aligned bounding boxes in world space are found to intersect for the first time. All behavior beyond that is determined by what SampleSubmarineFilterShader() returns.</p> +<p>The arguments of SampleSubmarineFilterShader() include PxFilterObjectAttributes and PxFilterData for the two objects, and a constant block of memory. Note that the pointers to the two objects are NOT passed, because those pointers refer to the computer's main memory, and that may, as we said, not be available to the shader, so the pointers would not be very useful, as dereferencing them would likely cause a crash. PxFilterObjectAttributes and PxFilterData are intended to contain all the useful information that one could quickly glean from the pointers. PxFilterObjectAttributes are 32 bits of data, that encode the type of object: For example PxFilterObjectType::eRIGID_STATIC, ::eRIGID_DYNAMIC, or even ::ePARTICLE_SYSTEM. Additionally, it lets you find out if the object is kinematic, or a trigger.</p> +<p>Each PxShape and PxParticleBase object in PhysX has a member variable of type PxFilterData. This is 128 bits of user defined data that can be used to store application specific information related to collision filtering. This is the other variable that is passed to SampleSubmarineFilterShader() for each object.</p> +<p>There is also the constant block. This is a chunk of per-scene global information that the application can give to the shader to operate on. You will want to use this to encode rules about what to filter and what not.</p> +<p>Finally, SampleSubmarineFilterShader() also has a PxPairFlags parameter. This is an output, like the return value PxFilterFlags, though used slightly differently. PxFilterFlags tells the SDK if it should ignore the pair for good (eKILL), ignore the pair while it is overlapping, but ask again, when filtering related data changes for one of the objects (eSUPPRESS), or call the low performance but more flexible CPU callback if the shader cannot decide (eCALLBACK).</p> +<p>PxPairFlags specifies additional flags that stand for actions that the simulation should take in the future for this pair. For example, eNOTIFY_TOUCH_FOUND means notify the user when the pair really starts to touch, not just potentially.</p> +<p>Let us look at what the above shader does:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// let triggers through</span> +<span class="k">if</span><span class="p">(</span><span class="n">PxFilterObjectIsTrigger</span><span class="p">(</span><span class="n">attributes0</span><span class="p">)</span> <span class="o">||</span> <span class="n">PxFilterObjectIsTrigger</span><span class="p">(</span><span class="n">attributes1</span><span class="p">))</span> +<span class="p">{</span> + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eTRIGGER_DEFAULT</span><span class="p">;</span> + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This means that if either object is a trigger, then perform default trigger behavior (notify the application about start and end of touch), and otherwise perform 'default' collision detection between them.</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// generate contacts for all that were not filtered above</span> +<span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eCONTACT_DEFAULT</span><span class="p">;</span> + +<span class="c1">// trigger the contact callback for pairs (A,B) where</span> +<span class="c1">// the filtermask of A contains the ID of B and vice versa.</span> +<span class="k">if</span><span class="p">((</span><span class="n">filterData0</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData1</span><span class="p">.</span><span class="n">word1</span><span class="p">)</span> <span class="o">&&</span> <span class="p">(</span><span class="n">filterData1</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData0</span><span class="p">.</span><span class="n">word1</span><span class="p">))</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eNOTIFY_TOUCH_FOUND</span><span class="p">;</span> + +<span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">;</span> +</pre></div> +</div> +<p>This says that for all other objects, perform 'default' collision handling. In addition, there is a rule based on the filterDatas that determines particular pairs where we ask for touch notifications. To understand what this means, we need to know the special meaning that the sample gives to the filterDatas.</p> +<p>The needs of the sample are very basic, so we will use a very simple scheme to take care of it. The sample first gives named codes to the different object types using a custom enumeration:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">FilterGroup</span> +<span class="p">{</span> + <span class="k">enum</span> <span class="n">Enum</span> + <span class="p">{</span> + <span class="n">eSUBMARINE</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">),</span> + <span class="n">eMINE_HEAD</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span><span class="p">),</span> + <span class="n">eMINE_LINK</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">2</span><span class="p">),</span> + <span class="n">eCRAB</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">3</span><span class="p">),</span> + <span class="n">eHEIGHTFIELD</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">4</span><span class="p">),</span> + <span class="p">};</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The sample identifies each shape's type by assigning its PxFilterData::word0 to this FilterGroup type. Then, it puts a bit mask that specifies each type of object that should generate a report when touched by an object of type word0 into word1. This could be done in the samples whenever a shape is created, but because shape creation is a bit encapsulated in SampleBase, it is done after the fact, using this function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">setupFiltering</span><span class="p">(</span><span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">actor</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">filterGroup</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">filterMask</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PxFilterData</span> <span class="n">filterData</span><span class="p">;</span> + <span class="n">filterData</span><span class="p">.</span><span class="n">word0</span> <span class="o">=</span> <span class="n">filterGroup</span><span class="p">;</span> <span class="c1">// word0 = own ID</span> + <span class="n">filterData</span><span class="p">.</span><span class="n">word1</span> <span class="o">=</span> <span class="n">filterMask</span><span class="p">;</span> <span class="c1">// word1 = ID mask to filter pairs that trigger a</span> + <span class="c1">// contact callback;</span> + <span class="k">const</span> <span class="n">PxU32</span> <span class="n">numShapes</span> <span class="o">=</span> <span class="n">actor</span><span class="o">-></span><span class="n">getNbShapes</span><span class="p">();</span> + <span class="n">PxShape</span><span class="o">**</span> <span class="n">shapes</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxShape</span><span class="o">**</span><span class="p">)</span><span class="n">SAMPLE_ALLOC</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="n">PxShape</span><span class="o">*</span><span class="p">)</span><span class="o">*</span><span class="n">numShapes</span><span class="p">);</span> + <span class="n">actor</span><span class="o">-></span><span class="n">getShapes</span><span class="p">(</span><span class="n">shapes</span><span class="p">,</span> <span class="n">numShapes</span><span class="p">);</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numShapes</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">PxShape</span><span class="o">*</span> <span class="n">shape</span> <span class="o">=</span> <span class="n">shapes</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> + <span class="n">shape</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">filterData</span><span class="p">);</span> + <span class="p">}</span> + <span class="n">SAMPLE_FREE</span><span class="p">(</span><span class="n">shapes</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This sets up the PxFilterDatas of each shape belonging to the passed actor. Here are some examples how this is used in SampleSubmarine:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">setupFiltering</span><span class="p">(</span><span class="n">mSubmarineActor</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eSUBMARINE</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eMINE_HEAD</span> <span class="o">|</span> + <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eMINE_LINK</span><span class="p">);</span> +<span class="n">setupFiltering</span><span class="p">(</span><span class="n">link</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eMINE_LINK</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eSUBMARINE</span><span class="p">);</span> +<span class="n">setupFiltering</span><span class="p">(</span><span class="n">mineHead</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eMINE_HEAD</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eSUBMARINE</span><span class="p">);</span> + +<span class="n">setupFiltering</span><span class="p">(</span><span class="n">heightField</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eHEIGHTFIELD</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eCRAB</span><span class="p">);</span> +<span class="n">setupFiltering</span><span class="p">(</span><span class="n">mCrabBody</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eCRAB</span><span class="p">,</span> <span class="n">FilterGroup</span><span class="o">::</span><span class="n">eHEIGHTFIELD</span><span class="p">);</span> +</pre></div> +</div> +<p>This scheme is probably too simplistic to use in a real game, but it shows the basic usage of the filter shader, and it will ensure that SampleSubmarine::onContact() is called for all interesting pairs.</p> +<p>An alternative group based filtering mechanism is provided with source in the extensions function PxDefaultSimulationFilterShader. And, again, if this shader based system is too inflexible, consider using the callback approach provided with PxSimulationFilterCallback.</p> +</div> +<div class="section" id="aggregates"> +<h2>Aggregates<a class="headerlink" href="#aggregates" title="Permalink to this headline">¶</a></h2> +<p>An aggregate is a collection of actors. Aggregates do not provide extra simulation or query features, but allow you to tell the SDK that a set of actors will be clustered together, which in turn allows the SDK to optimize its spatial data operations. A typical use case is a ragdoll, made of multiple different actors. Without aggregates, this gives rise to as many broad-phase entries as there are shapes in the ragdoll. It is typically more efficient to represent the ragdoll in the broad-phase as a single entity, and perform internal overlap tests in a second pass if necessary. Another potential use case is a single actor with a large number of attached shapes.</p> +</div> +<div class="section" id="creating-an-aggregate"> +<h2>Creating an Aggregate<a class="headerlink" href="#creating-an-aggregate" title="Permalink to this headline">¶</a></h2> +<p>Create an aggregate from the <em>PxPhysics</em> object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span><span class="p">;</span> <span class="c1">// The physics SDK object</span> + +<span class="n">PxU32</span> <span class="n">nbActors</span><span class="p">;</span> <span class="c1">// Max number of actors expected in the aggregate</span> +<span class="kt">bool</span> <span class="n">selfCollisions</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span> + +<span class="n">PxAggregate</span><span class="o">*</span> <span class="n">aggregate</span> <span class="o">=</span> <span class="n">physics</span><span class="o">-></span><span class="n">createAggregate</span><span class="p">(</span><span class="n">nbActors</span><span class="p">,</span> <span class="n">selfCollisions</span><span class="p">);</span> +</pre></div> +</div> +<p>The maximum number of actors is currently limited to 128, and for efficiency should be set as low as possible.</p> +<p>If you will never need collisions between the actors of the aggregate, disable them at creation time. This is much more efficient than using the scene filtering mechanism, as it bypasses all internal filtering logic. A typical use case would be an aggregate of static or kinematic actors.</p> +<p>Note that both the maximum number of actors and the self-collision attribute are immutable.</p> +</div> +<div class="section" id="populating-an-aggregate"> +<h2>Populating an Aggregate<a class="headerlink" href="#populating-an-aggregate" title="Permalink to this headline">¶</a></h2> +<p>Adds an actor to an aggregate as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxActor</span><span class="o">&</span> <span class="n">actor</span><span class="p">;</span> <span class="c1">// Some actor, previously created</span> +<span class="n">aggregate</span><span class="o">-></span><span class="n">addActor</span><span class="p">(</span><span class="n">actor</span><span class="p">);</span> +</pre></div> +</div> +<p>Note that if the actor already belongs to a scene, the call is ignored. Either add the actors to an aggregate and then add the aggregate to the scene, or add the aggregate to the scene and then the actors to the aggregate.</p> +<p>To add the aggregate to a scene (before or after populating it):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">addAggregate</span><span class="p">(</span><span class="o">*</span><span class="n">aggregate</span><span class="p">);</span> +</pre></div> +</div> +<p>Similarly, to remove the aggregate from the scene:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">removeAggregate</span><span class="p">(</span><span class="o">*</span><span class="n">aggregate</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="releasing-an-aggregate"> +<h2>Releasing an Aggregate<a class="headerlink" href="#releasing-an-aggregate" title="Permalink to this headline">¶</a></h2> +<p>To release an aggregate:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxAggregate</span><span class="o">*</span> <span class="n">aggregate</span><span class="p">;</span> <span class="c1">// The aggregate we previously created</span> +<span class="n">aggregate</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>Releasing the PxAggregate does not release the aggregated actors. If the PxAggregate belongs to a scene, the actors are automatically re-inserted in that scene. If you intend to delete both the PxAggregate and its actors, it is most efficient to release the actors first, then release the PxAggregate when it is empty.</p> +</div> +<div class="section" id="amortizing-insertion"> +<h2>Amortizing Insertion<a class="headerlink" href="#amortizing-insertion" title="Permalink to this headline">¶</a></h2> +<p>Adding many objects to a scene in one frame can be a costly operation. This can be the case for a ragdoll, which as discussed is a good candidate for PxAggregate. Another case is localized debris, for which self-collisions are often disabled. To amortize the cost of object insertion into the broad-phase structure over several, spawn the debris in a PxAggregate, then remove each actor from the aggregate and and re-insert it into the scene over those frames.</p> +</div> +<div class="section" id="trigger-shapes"> +<h2>Trigger Shapes<a class="headerlink" href="#trigger-shapes" title="Permalink to this headline">¶</a></h2> +<p>Trigger shapes play no part in the simulation of the scene (though they can be configured to participate in scene queries). Instead, their role is to report that there has been an overlap with another shape. Contacts are not generated for the intersection, and as a result contact reports are not available for trigger shapes. Further, because triggers play no part in the simulation, the SDK will not allow the the eSIMULATION_SHAPE eTRIGGER_SHAPE flags to be raised simultaneously; that is, if one flag is raised then attempts to raise the other will be rejected, and an error will be passed to the error stream.</p> +<p>Trigger shapes have been used in SampleSubmarine to determine if the submarine has reached the treasure. In the following code the PxActor representing the treasure has its solitary shape configured as a trigger shapes:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">treasureShape</span><span class="p">;</span> +<span class="n">gTreasureActor</span><span class="o">-></span><span class="n">getShapes</span><span class="p">(</span><span class="o">&</span><span class="n">treasureShape</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span> +<span class="n">treasureShape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">eSIMULATION_SHAPE</span><span class="p">,</span> <span class="nb">false</span><span class="p">);</span> +<span class="n">treasureShape</span><span class="o">-></span><span class="n">setFlag</span><span class="p">(</span><span class="n">PxShapeFlag</span><span class="o">::</span><span class="n">eTRIGGER_SHAPE</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>The overlaps with trigger shapes are reported in SampleSubmarine through the implementation of PxSimulationEventCallback::onTrigger in the PxSampleSubmarine class, a sub-class of PxSimulationEventCallback:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">SampleSubmarine</span><span class="o">::</span><span class="n">onTrigger</span><span class="p">(</span><span class="n">PxTriggerPair</span><span class="o">*</span> <span class="n">pairs</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">count</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">// ignore pairs when shapes have been deleted</span> + <span class="k">if</span> <span class="p">(</span><span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">flags</span> <span class="o">&</span> <span class="p">(</span><span class="n">PxTriggerPairFlag</span><span class="o">::</span><span class="n">eREMOVED_SHAPE_TRIGGER</span> <span class="o">|</span> + <span class="n">PxTriggerPairFlag</span><span class="o">::</span><span class="n">eREMOVED_SHAPE_OTHER</span><span class="p">))</span> + <span class="k">continue</span><span class="p">;</span> + + <span class="k">if</span> <span class="p">((</span><span class="o">&</span><span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">otherShape</span><span class="o">-></span><span class="n">getActor</span><span class="p">()</span> <span class="o">==</span> <span class="n">mSubmarineActor</span><span class="p">)</span> <span class="o">&&</span> + <span class="p">(</span><span class="o">&</span><span class="n">pairs</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">triggerShape</span><span class="o">-></span><span class="n">getActor</span><span class="p">()</span> <span class="o">==</span> <span class="n">gTreasureActor</span><span class="p">))</span> + <span class="p">{</span> + <span class="n">gTreasureFound</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The code above iterates through all pairs of overlapping shapes that involve a trigger shape. If it is found that the treasure has been touched by the submarine then the flag gTreasureFound is set true.</p> +</div> +<div class="section" id="interactions"> +<h2>Interactions<a class="headerlink" href="#interactions" title="Permalink to this headline">¶</a></h2> +<p>The SDK internally creates an interaction object for each overlapping pair reported by the broad-phase. These objects are not only created for pairs of colliding rigid bodies, but also for pairs of overlapping triggers. Generally speaking users should assume that such objects are created regardless of the involved objects' types (rigid body, trigger, cloth, etc) and regardless of involved <em>PxFilterFlag</em> flags.</p> +<p>There is currently a limit of 65535 such interaction objects for each actor. If more than 65535 interactions involve the same actor, then the SDK outputs an error message and the extra interactions are ignored.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Rigid Body Collision</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#shapes">Shapes</a></li> +<li><a class="reference internal" href="#simulation-shapes-and-scene-query-shapes">Simulation Shapes and Scene Query Shapes</a></li> +<li><a class="reference internal" href="#kinematic-triangle-meshes-planes-heighfields">Kinematic Triangle Meshes (Planes, Heighfields)</a></li> +<li><a class="reference internal" href="#broad-phase-algorithms">Broad-phase Algorithms</a></li> +<li><a class="reference internal" href="#regions-of-interest">Regions of Interest</a></li> +<li><a class="reference internal" href="#broad-phase-callback">Broad-phase Callback</a></li> +<li><a class="reference internal" href="#collision-filtering">Collision Filtering</a></li> +<li><a class="reference internal" href="#aggregates">Aggregates</a></li> +<li><a class="reference internal" href="#creating-an-aggregate">Creating an Aggregate</a></li> +<li><a class="reference internal" href="#populating-an-aggregate">Populating an Aggregate</a></li> +<li><a class="reference internal" href="#releasing-an-aggregate">Releasing an Aggregate</a></li> +<li><a class="reference internal" href="#amortizing-insertion">Amortizing Insertion</a></li> +<li><a class="reference internal" href="#trigger-shapes">Trigger Shapes</a></li> +<li><a class="reference internal" href="#interactions">Interactions</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="RigidBodyOverview.html" + title="previous chapter">Rigid Body Overview</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="RigidBodyDynamics.html" + title="next chapter">Rigid Body Dynamics</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" /> + <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="RigidBodyDynamics.html" title="Rigid Body Dynamics" + >next</a></li> + <li class="right" > + <a href="RigidBodyOverview.html" title="Rigid Body Overview" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyDynamics.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyDynamics.html new file mode 100644 index 00000000..c56dc691 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyDynamics.html @@ -0,0 +1,541 @@ +<!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>Rigid Body Dynamics — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Simulation" href="Simulation.html" /> + <link rel="prev" title="Rigid Body Collision" href="RigidBodyCollision.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Simulation.html" title="Simulation" + accesskey="N">next</a></li> + <li class="right" > + <a href="RigidBodyCollision.html" title="Rigid Body Collision" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="rigid-body-dynamics"> +<span id="rigidbodydynamics"></span><h1>Rigid Body Dynamics<a class="headerlink" href="#rigid-body-dynamics" title="Permalink to this headline">¶</a></h1> +<p>In this chapter we cover a number of topics that are also important to understand once you are comfortable with setting up a basic rigid body simulation world.</p> +<div class="section" id="velocity"> +<h2>Velocity<a class="headerlink" href="#velocity" title="Permalink to this headline">¶</a></h2> +<p>A rigid body's motion is separated into linear and angular velocity components. During simulation, PhysX will modify the velocity of an object in accordance with gravity, other applied forces and torques and as a result of various constraints, such as collisions or joints.</p> +<p>A body's linear and angular velocities can be read using the following methods:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVec3</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">getLinearVelocity</span><span class="p">();</span> +<span class="n">PxVec3</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">getAngularVelocity</span><span class="p">();</span> +</pre></div> +</div> +<p>A body's linear and angular velocities can be set using the following methods:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">setLinearVelocity</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">linVel</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">setAngularVelocity</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">angVel</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="mass-properties"> +<h2>Mass Properties<a class="headerlink" href="#mass-properties" title="Permalink to this headline">¶</a></h2> +<p>A dynamic actor needs mass properties: the mass, moment of inertia, and the center of mass frame which specifies the position of the actor's center of mass and its principal inertia axes. The easiest way to calculate mass properties is to use the PxRigidBodyExt::updateMassAndInertia() helper function, which will set all three properties based on the actor's shapes and a uniform density value. Variants of this function allow combinations of per-shape densities and manual specification of some mass properties. See the reference for PxRigidBodyExt for more details.</p> +<p>The Wobbly Snowmen in the North Pole Sample illustrate the use of different mass properties. The snowmen act like roly-poly toys, which are usually just an empty shell with the bottom filled with some heavy material. The low centers of mass cause them to move back to an upright position after they have been tilted. They come in different flavors, depending on how the mass properties are set:</p> +<p>The first is basically massless. There is just a little sphere with a relatively high mass at the bottom of the Actor. This results in a quite rapid movement due to the small resulting moments of inertia. The snowman feels light.</p> +<p>The second uses the mass of the bottom snowball only, resulting in a bigger inertia. Later on, the center of mass is moved to the bottom of the actor. This approximation is by no means physically correct, but the resulting snowman feels a bit more filled.</p> +<p>The third and fourth snowman use shapes to calculate the mass. The difference is that one calculates the moments of inertia first (from the real center of mass) and then the center of mass is moved to the bottom. The other calculates the moments of inertia about the low center of mass that we pass to the calculation routine. Note how much slower the wobbling is for the second case although both have the same mass. This is because the head accounts for much more in the moment of inertia (the distance from the center of mass squared).</p> +<p>The last snowman's mass properties are set up manually. The sample uses rough values for the moment of inertia to create a specific desired behavior. The diagonal tensor has a low value in X, and high values in Y and Z, producing a low resistance to rotation around the X-axis and high resistance around Y and Z. As a consequence, the snowman will wobble back and forth only around the X axis.</p> +<p>If you have a 3x3 inertia matrix (for example, you have real-life inertia tensors for your objects) use the PxDiagonalize() function to obtain principal axes and diagonal inertia tensors to initialize PxRigidDynamic actors.</p> +<p>When manually setting the mass/inertia tensor of bodies, PhysX requires positive values for the mass and each principal axis of inertia. However, it is legal to provide 0s in these values. When provided with a 0 mass or inertia value, PhysX interprets this to mean infinite mass or inertia around that principal axis. This can be used to create bodies that resist all linear motion or that resist all or some angular motion. Examples of the effects that could be achieved using this approach are:</p> +<ul class="simple"> +<li>Bodies that behave as if they were kinematic.</li> +<li>Bodies whose translation behaves kinematically but whose rotation is dynamic.</li> +<li>Bodies whose translation is dynamic but whose rotation is kinematic.</li> +<li>Bodies which can only rotate around a specific axis.</li> +</ul> +<p>Some examples of what could be achieved are detailed below. First, let's assume that we are creating a common structure - a windmill. The code to construct the bodies that would be part of the windmill are provided below:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dyn</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">2.5f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">)));</span> +<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">dyn</span><span class="p">,</span> <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="mf">2.f</span><span class="p">,</span> <span class="mf">0.2f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">),</span> <span class="n">material</span><span class="p">);</span> +<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">dyn</span><span class="p">,</span> <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="mf">0.2f</span><span class="p">,</span> <span class="mf">2.f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">),</span> <span class="n">material</span><span class="p">);</span> +<span class="n">dyn</span><span class="o">-></span><span class="n">setActorFlag</span><span class="p">(</span><span class="n">PxActorFlag</span><span class="o">::</span><span class="n">eDISABLE_GRAVITY</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +<span class="n">dyn</span><span class="o">-></span><span class="n">setAngularVelocity</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">,</span> <span class="mf">5.f</span><span class="p">));</span> +<span class="n">dyn</span><span class="o">-></span><span class="n">setAngularDamping</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span> +<span class="n">PxRigidStatic</span><span class="o">*</span> <span class="n">st</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="p">.</span><span class="n">createRigidStatic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">1.5f</span><span class="p">,</span> <span class="o">-</span><span class="mf">1.f</span><span class="p">)));</span> +<span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">t</span><span class="p">,</span> <span class="n">PxBoxGeometry</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">,</span> <span class="mf">1.5f</span><span class="p">,</span> <span class="mf">0.8f</span><span class="p">),</span> <span class="n">material</span><span class="p">);</span> +<span class="n">scene</span><span class="p">.</span><span class="n">addActor</span><span class="p">(</span><span class="n">dyn</span><span class="p">);</span> +<span class="n">scene</span><span class="p">.</span><span class="n">addActor</span><span class="p">(</span><span class="n">st</span><span class="p">);</span> +</pre></div> +</div> +<p>The above code creates a static box frame for the windmill and a cross to represent the blades of the turbine. We turn off gravity and angular damping on the windmill blade and give it an initial angular velocity. As a result, this turbine blade will rotate at a constant angular velocity indefinitely. However, if another object collided with the turbine, our windmill would cease to function correctly because the turbine blade would be knocked out of place. There are several options to make the turbine blade stay in the correct position when other bodies interact with it. One such approach might be to make the turbine have infinite mass and inertia. In this case, any interactions with bodies would not affect the turbine at all:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">dyn</span><span class="o">-></span><span class="n">setMass</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span> +<span class="n">dyn</span><span class="o">-></span><span class="n">setMassSpaceInertiaTensor</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">));</span> +</pre></div> +</div> +<p>This example retains the previous behavior of the turbine spinning at a constant angular velocity indefinitely. However, now the body's velocities cannot be affected by any constraints because the body has infinite mass and inertia. If a body collided with the turbine blade, the collision would behave as if the turbine blade was a kinematic body.</p> +<p>Another alternative would be to make the turbine have infinite mass and limit its rotation to just around the body's local z-axis. This would provide the same effect as applying a revolute joint between the turbine and the static windmill frame:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">dyn</span><span class="o">-></span><span class="n">setMass</span><span class="p">(</span><span class="mf">0.f</span><span class="p">);</span> +<span class="n">dyn</span><span class="o">-></span><span class="n">setMassSpaceInertiaTensor</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">,</span> <span class="mf">10.f</span><span class="p">));</span> +</pre></div> +</div> +<p>In both examples, the body's mass was set to 0, indicating that the body has infinite mass so its linear velocity cannot be changed by any constraints. However, in this example, the body's inertia is configured to permit the body's angular velocity to be affected by constraints around one principal axis or inertia. This provides a similar effect to introducing a revolute joint. The value of the inertia around the z-axis can be increased or decreased to make the turbines more/less resistive to motion.</p> +</div> +<div class="section" id="applying-forces-and-torques"> +<h2>Applying Forces and Torques<a class="headerlink" href="#applying-forces-and-torques" title="Permalink to this headline">¶</a></h2> +<p>The most physics-friendly way to interact with a body is to apply a force to it. In classical mechanics, most interactions between bodies are typically solved by using forces. Because of the law:</p> +<blockquote> +<div>f = m*a (force = mass * acceleration)</div></blockquote> +<p>Forces directly control a body's acceleration, but its velocity and position only indirectly. For this reason control by force may be inconvenient if you need immediate response. The advantage of forces is that regardless of what forces you apply to the bodies in the scene, the simulation will be able to keep all the defined constraints (joints and contacts) satisfied. For example gravity works by applying a force to bodies.</p> +<p>Unfortunately applying large forces to articulated bodies at the resonant frequency of a system may lead to ever increasing velocities, and eventually to the failure of the solver to maintain the joint constraints. This is not unlike a real world system, where the joints would ultimately break.</p> +<p>The forces acting on a body are accumulated before each simulation frame, applied to the simulation, and then reset to zero in preparation for the next frame. The relevant methods of PxRigidBody and PxRigidBodyExt are listed below. Please refer to the API reference for more detail:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">addForce</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">force</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxRigidBody</span><span class="o">::</span><span class="n">addTorque</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">torque</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">autowake</span><span class="p">);</span> + +<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addForceAtPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">force</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addForceAtLocalPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">force</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addLocalForceAtPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">force</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">addLocalForceAtLocalPos</span><span class="p">(</span><span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">force</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">pos</span><span class="p">,</span> <span class="n">PxForceMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">mode</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">wakeup</span><span class="p">);</span> +</pre></div> +</div> +<p>The PxForceMode member defaults to PxForceMode::eFORCE to apply simple forces. There are other possibilities. For example PxForceMode::eIMPULSE will apply an impulsive force. PxForceMode::eVELOCITY_CHANGE will do the same, but also ignore the mass of the body, effectively leading to an instantaneous velocity change. See the API documentation of PxForceMode for the other possibilities.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The methods in PxRigidBodyExt support only the force modes eFORCE and eIMPULSE.</p> +</div> +<p>There are further extension functions that compute the linear and angular velocity changes that would arise in the next simulation frame if an impulsive force or impulsive torque were to be applied:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidBodyExt</span><span class="o">::</span><span class="n">computeVelocityDeltaFromImpulse</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRigidBody</span><span class="o">&</span> <span class="n">body</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">impulsiveForce</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">impulsiveTorque</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">deltaLinearVelocity</span><span class="p">,</span> + <span class="n">PxVec3</span><span class="o">&</span> <span class="n">deltaAngularVelocity</span><span class="p">);</span> +</pre></div> +</div> +<p>A use case for this function might be to predict an updated velocity for a game object so that asset loading may be initiated in advance of the simulation frame if the body is likely to exceed a threshold velocity at the end of the frame. The impulsive force and torque are simply the force and torque that are to be applied to the body multiplied by the timestep of the simulation frame. Neglecting the effect of constraint and contact forces, the change in linear and angular velocity that are expected to arise in the next simulation frame are returned in deltaLinearVelocity and deltaAngularVelocity. The predicted linear velocity can then be computed with body.getLinearVelocity() + deltaLinearVelocity, while the predicted angular velocity can be computed with body.getAngularVelocity() + deltaAngularVelocity. If required, it is possible to immediately update the velocity of the body using body.setLinearVelocity(body.getLinearVelocity() + deltaLinearVelocity) and body.setAngularVelocity(body.getAngularVelocity() + deltaAngularVelocity).</p> +</div> +<div class="section" id="gravity"> +<h2>Gravity<a class="headerlink" href="#gravity" title="Permalink to this headline">¶</a></h2> +<p>Gravity is such a common force in simulations that PhysX makes it particularly simple to apply. For a scene-wide gravity effect, or any other uniform force field, set the PxScene class' gravity vector using PxScene::setGravity().</p> +<p>The parameter is the acceleration due to gravity. In meters and seconds, this works out to have a magnitude of about 9.8 on earth, and should point downwards. The force that will be applied at the center of mass of each body in the scene is this acceleration vector times the actor's mass.</p> +<p>Certain special effects can require that some dynamic actors are not influenced by gravity. To specify this set the flag:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxActor</span><span class="o">::</span><span class="n">setActorFlag</span><span class="p">(</span><span class="n">PxActorFlag</span><span class="o">::</span><span class="n">eDISABLE_GRAVITY</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Be careful when changing gravity (or enabling/disabling it) during the simulation. For performance reasons the change will not wake up sleeping actors automatically. Thus it may be necessary to iterate through all actors and call PxRigidDynamic::wakeUp() manually.</p> +</div> +<p>An alternative to PxActorFlag::eDISABLE_GRAVITY is to use a zero gravity vector for the whole scene, then apply your own gravity force to rigid bodies, each frame. This can be used to create radial gravity fields, as demonstrated in SampleCustomGravity.</p> +</div> +<div class="section" id="friction-and-restitution"> +<h2>Friction and Restitution<a class="headerlink" href="#friction-and-restitution" title="Permalink to this headline">¶</a></h2> +<p>All physical objects have at least one material, which defines the friction and restitution properties used to resolve a collision with the objects.</p> +<p>To create a material, call PxPhysics::createMaterial():</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxMaterial</span><span class="o">*</span> <span class="n">mMaterial</span><span class="p">;</span> + +<span class="n">mMaterial</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-></span><span class="n">createMaterial</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">,</span> <span class="mf">0.5f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">);</span> <span class="c1">// static friction, dynamic friction,</span> + <span class="c1">// restitution</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">mMaterial</span><span class="p">)</span> + <span class="n">fatalError</span><span class="p">(</span><span class="s">"createMaterial failed!"</span><span class="p">);</span> +</pre></div> +</div> +<p>Materials are owned by the PxPhysics object, and can be shared among objects in multiple scenes. The material properties of two objects involved in a collision may be combined in various ways. See the reference documentation for PxMaterial for more details.</p> +<p>PhysX objects whose collision geometry is a triangle mesh or a heightfield (see <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollisionshapes"><em>Shapes</em></a>) can have a material per triangle.</p> +<p>Friction uses the coulomb friction model, which is based around the concepts of 2 coefficients: the static friction coefficient and the dynamic friction coefficient (sometimes called kinetic friction). Friction resists relative lateral motion of two solid surfaces in contact. These two coefficients define a relationship between the normal force exerted by each surface on the other and the amount of friction force that is applied to resist lateral motion. Static friction defines the amount of friction that is applied between surfaces that are not moving lateral to each-other. Dynamic friction defines the amount of friction applied between surfaces that are moving relative to each-other.</p> +<p>The coefficient of restitution of two colliding objects is a fractional value representing the ratio of speeds after and before an impact, taken along the line of impact. A coefficient of restitution of 1 is said to collide elastically, while a coefficient of restitution < 1 is said to be inelastic.</p> +</div> +<div class="section" id="sleeping"> +<span id="id1"></span><h2>Sleeping<a class="headerlink" href="#sleeping" title="Permalink to this headline">¶</a></h2> +<p>When an actor does not move for a period of time, it is assumed that it will not move in the future either until some external force acts on it that throws it out of equilibrium. Until then it is no longer simulated in order to save resources. This state is called sleeping. You can query an actor's sleep state with the following method:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">isSleeping</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> +</pre></div> +</div> +<p>It is however often more convenient to listen for events that the SDK sends when actors fall asleep or wake up. To receive the following events, PxActorFlag::eSEND_SLEEP_NOTIFIES must be set for the actor:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onWake</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onSleep</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>See the section <a class="reference internal" href="Simulation.html#callbacks"><em>Callback Sequence</em></a> and the subsection <a class="reference internal" href="#sleep-callbacks"><em>Sleep state change events</em></a> for more information.</p> +<p>An actor goes to sleep when its kinetic energy is below a given threshold for a certain time. Basically, every dynamic rigid actor has a wake counter which gets decremented by the simulation time step when the kinetic energy of the actor is below the specified threshold. However, if the energy is above the threshold after a simulation step, the counter gets reset to a minimum default value and the whole process starts anew. Once the wake counter reaches zero, it does not get decremented any further and the actor is ready to go to sleep. Please note that a zero wake counter does not mean that the actor has to be asleep, it only indicates that it is ready to go to sleep. There are other factors that might keep an actor awake for a while longer.</p> +<p>The energy threshold as well as the minimum amount of time an actor will stay awake can be manipulated using the following methods:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">setSleepThreshold</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">threshold</span><span class="p">);</span> +<span class="n">PxReal</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">getSleepThreshold</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> + +<span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">setWakeCounter</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">wakeCounterValue</span><span class="p">);</span> +<span class="n">PxReal</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">getWakeCounter</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">For kinematic actors, special sleep rules apply. A kinematic actor is asleep unless a target pose has been set (in which case it will stay awake until the end of the next simulation step where no target pose has been set anymore). As a consequence, it is not allowed to use setWakeCounter() for kinematic actors. The wake counter of a kinematic actor is solely defined based on whether a target pose has been set.</p> +</div> +<p>If a dynamic rigid actor is sleeping, the following state is guaranteed:</p> +<ul class="simple"> +<li>The wake counter is zero.</li> +<li>The linear and angular velocity is zero.</li> +<li>There is no force update pending.</li> +</ul> +<p>When an actor gets inserted into a scene, it will be considered asleep if all the points above hold, else it will be treated as awake.</p> +<p>In general, a dynamic rigid actor is guaranteed to be awake if at least one of the following holds:</p> +<ul class="simple"> +<li>The wake counter is positive.</li> +<li>The linear or angular velocity is non-zero.</li> +<li>A non-zero force or torque has been applied.</li> +</ul> +<p>As a consequence, the following calls will wake the actor up automatically:</p> +<ul class="simple"> +<li>PxRigidDynamic::setWakeCounter(), if the wake counter value is larger than zero.</li> +<li>PxRigidBody::setLinearVelocity(), ::setAngularVelocity(), if the velocity is non-zero.</li> +<li>PxRigidBody::addForce(), ::addTorque(), if the torque is non-zero.</li> +</ul> +<p>In addition, the following calls and events wake an actor up:</p> +<ul class="simple"> +<li>PxRigidDynamic::setKinematicTarget() in the case of a kinematic actor (because this also sets the wake counter to a positive value).</li> +<li>PxRigidActor::setGlobalPose(), if the autowake parameter is set to true (default).</li> +<li>Simulation gets disabled for a PxRigidActor by raising PxActorFlag::eDISABLE_SIMULATION.</li> +<li>PxScene::resetFiltering().</li> +<li>PxShape::setSimulationFilterData(), if the subsequent re-filtering causes the type of the shape pair to transition between suppressed, trigger and contact.</li> +<li>Touch with an actor that is awake.</li> +<li>A touching rigid actor gets removed from the scene (this is the default behavior but it can be specified by the user, see note further below).</li> +<li>Contact with a static rigid actor is lost.</li> +<li>Contact with a dynamic rigid actor is lost and this actor is awake in the next simulation step.</li> +<li>The actor gets hit by a two-way interaction particle.</li> +</ul> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">When removing a rigid actor from the scene or a shape from an actor, it is possible to specify whether to wake up the objects that were touching the removed object in the previous simulation step. See the API comments in PxScene::removeActor() and PxRigidActor::detachShape() for details.</p> +</div> +<p>To explicitly wake up a sleeping object, or force an object to sleep, use:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">wakeUp</span><span class="p">();</span> +<span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">putToSleep</span><span class="p">();</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">It is not allowed to use these methods for kinematic actors. The sleep state of a kinematic actor is solely defined based on whether a target pose has been set.</p> +</div> +<p>The API reference documents exactly which methods cause an actor to be woken up.</p> +<div class="section" id="sleep-state-change-events"> +<span id="sleep-callbacks"></span><h3>Sleep state change events<a class="headerlink" href="#sleep-state-change-events" title="Permalink to this headline">¶</a></h3> +<p>As mentioned above, PhysX provides an event system that reports changes to the sleep state of dynamic rigid bodies during <em>PxScene::fetchResults()</em>:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onWake</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="kt">void</span> <span class="n">PxSimulationEventCallback</span><span class="o">::</span><span class="n">onSleep</span><span class="p">(</span><span class="n">PxActor</span><span class="o">**</span> <span class="n">actors</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">count</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>It is important to understand the correct usage of these events, and their limitations:</p> +<ul class="simple"> +<li>A body added since the previous <em>fetchResults()</em> or <em>flushSimulation()</em> will always generate an event, even if no sleep state transition occured.</li> +<li>If there have been multiple changes in a body's sleep state since the previous <em>fetchResults()</em> or <em>flushSimulation()</em>, PhysX will report only the most recent.</li> +</ul> +<p>Sometimes it is desirable to detect transitions between awake and asleep, e.g. when keeping track of the number of awake bodies. Suppose a sleeping body <em>B</em> is woken by the application, the counter is incremented, and during the next simulation step <em>B</em> stays awake. Even though <em>B</em>'s sleep state did not change during simulation, it has changed since the previous <em>fetchResults()</em>, and so an <em>onWake()</em> event will be generated for it. If the counter is incremented again in response to this event, its value will be incorrect.</p> +<p>To use sleep state events to detect transitions, a record of the sleep state for objects of interest has to be kept, for example in a hash. When processing an event, this record can be used to check whether there has been a transition.</p> +</div> +</div> +<div class="section" id="kinematic-actors"> +<h2>Kinematic Actors<a class="headerlink" href="#kinematic-actors" title="Permalink to this headline">¶</a></h2> +<p>Sometimes controlling an actor using forces or constraints is not sufficiently robust, precise or flexible. For example moving platforms or character controllers often need to manipulate an actor's position or have it exactly follow a specific path. Such a control scheme is provided by kinematic actors.</p> +<p>A kinematic actor is controlled using the PxRigidDynamic::setKinematicTarget() function. Each simulation step PhysX moves the actor to its target position, regardless of external forces, gravity, collision, etc. Thus one must continually call setKinematicTarget(), every time step, for each kinematic actor, to make them move along their desired paths. The movement of a kinematic actor affects dynamic actors with which it collides or to which it is constrained with a joint. The actor will appear to have infinite mass and will push regular dynamic actors out of the way.</p> +<p>To create a kinematic actor, simply create a regular dynamic actor then set its kinematic flag:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidBody</span><span class="o">::</span><span class="n">setRigidBodyFlag</span><span class="p">(</span><span class="n">PxRigidBodyFlag</span><span class="o">::</span><span class="n">eKINEMATIC</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>Use the same function to transform a kinematic actor back to a regular dynamic actor. While you do need to provide a mass for the kinematic actor as for all dynamic actors, this mass will not actually be used for anything while the actor is in kinematic mode.</p> +<p>Caveats:</p> +<ul class="simple"> +<li>It is important to understand the difference between PxRigidDynamic::setKinematicTarget() and PxRigidActor::setGlobalPose() here. While setGlobalPose() would also move the actor to the desired position, it would not make that actor properly interact with other objects. In particular, with setGlobalPose() the kinematic actor would not push away other dynamic actors in its path, instead it would go right through them. The setGlobalPose() function can still be used though, if one simply wants to teleport a kinematic actor to a new position.</li> +<li>A kinematic actor can push away dynamic objects, but nothing pushes it back. As a result, a kinematic can easily squish a dynamic actor against a static actor, or against another kinematic actor. As a result, the squished dynamic object can deeply penetrate the geometry it has been pushed into.</li> +<li>There is no interaction or collision between kinematic actors and static actors. However, it is possible to request contact information for these cases if PxSceneFlag::eENABLE_KINEMATIC_PAIRS or ::eENABLE_KINEMATIC_STATIC_PAIRS gets set.</li> +</ul> +</div> +<div class="section" id="active-transforms"> +<h2>Active Transforms<a class="headerlink" href="#active-transforms" title="Permalink to this headline">¶</a></h2> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">the active transforms are currently deprecated. See next paragraph about Active Actors for its replacement.</p> +</div> +<p>The active transforms API provides an efficient way to reflect actor transform changes in a PhysX scene to an associated external object such as a render mesh.</p> +<p>When a scene's fetchResults() method is called an array of <em>PxActiveTransform</em> structs is generated, each entry in the array contains a pointer to the actor that moved, its user data and its new transform. Because only actors that have moved will be included in the list this approach is potentially much more efficient than, for example, analyzing each actor in the scene individually.</p> +<p>The example below shows how to use active transforms to update a render object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// update scene</span> +<span class="n">scene</span><span class="p">.</span><span class="n">simulate</span><span class="p">(</span><span class="n">dt</span><span class="p">);</span> +<span class="n">scene</span><span class="p">.</span><span class="n">fetchResults</span><span class="p">();</span> + +<span class="c1">// retrieve array of actors that moved</span> +<span class="n">PxU32</span> <span class="n">nbActiveTransforms</span><span class="p">;</span> +<span class="n">PxActiveTransform</span><span class="o">*</span> <span class="n">activeTransforms</span> <span class="o">=</span> <span class="n">scene</span><span class="p">.</span><span class="n">getActiveTransforms</span><span class="p">(</span><span class="n">nbActiveTransforms</span><span class="p">);</span> + +<span class="c1">// update each render object with the new transform</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">nbActiveTransforms</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">MyRenderObject</span><span class="o">*</span> <span class="n">renderObject</span> <span class="o">=</span> <span class="k">static_cast</span><span class="o"><</span><span class="n">MyRenderObject</span><span class="o">*></span><span class="p">(</span><span class="n">activeTransforms</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">userData</span><span class="p">);</span> + <span class="n">renderObject</span><span class="o">-></span><span class="n">setTransform</span><span class="p">(</span><span class="n">activeTransforms</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">actor2World</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">PxSceneFlag::eENABLE_ACTIVETRANSFORMS must be set on the scene for the active transforms array to be generated.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Since the target transform for kinematic rigid bodies is set by the user, kinematics can be excluded from the list by setting the flag PxSceneFlag::eEXCLUDE_KINEMATICS_FROM_ACTIVE_ACTORS.</p> +</div> +</div> +<div class="section" id="active-actors"> +<h2>Active Actors<a class="headerlink" href="#active-actors" title="Permalink to this headline">¶</a></h2> +<p>The active actors API provides an efficient way to reflect actor transform changes in a PhysX scene to an associated external object such as a render mesh.</p> +<p>When a scene's fetchResults() method is called an array of active <em>PxActor</em> is generated. Because only actors that have moved will be included in the list this approach is potentially much more efficient than, for example, analyzing each actor in the scene individually.</p> +<p>The example below shows how to use active actors to update a render object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// update scene</span> +<span class="n">scene</span><span class="p">.</span><span class="n">simulate</span><span class="p">(</span><span class="n">dt</span><span class="p">);</span> +<span class="n">scene</span><span class="p">.</span><span class="n">fetchResults</span><span class="p">();</span> + +<span class="c1">// retrieve array of actors that moved</span> +<span class="n">PxU32</span> <span class="n">nbActiveActors</span><span class="p">;</span> +<span class="n">PxActor</span><span class="o">**</span> <span class="n">activeActors</span> <span class="o">=</span> <span class="n">scene</span><span class="p">.</span><span class="n">getActiveActors</span><span class="p">(</span><span class="n">nbActiveActors</span><span class="p">);</span> + +<span class="c1">// update each render object with the new transform</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">nbActiveActors</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">MyRenderObject</span><span class="o">*</span> <span class="n">renderObject</span> <span class="o">=</span> <span class="k">static_cast</span><span class="o"><</span><span class="n">MyRenderObject</span><span class="o">*></span><span class="p">(</span><span class="n">activeActors</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">userData</span><span class="p">);</span> + <span class="n">renderObject</span><span class="o">-></span><span class="n">setTransform</span><span class="p">(</span><span class="n">activeActors</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">-></span><span class="n">getGlobalPose</span><span class="p">());</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">PxSceneFlag::eENABLE_ACTIVE_ACTORS must be set on the scene for the active actors array to be generated.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Since the target transform for kinematic rigid bodies is set by the user, kinematics can be excluded from the list by setting the flag PxSceneFlag::eEXCLUDE_KINEMATICS_FROM_ACTIVE_ACTORS.</p> +</div> +</div> +<div class="section" id="dominance"> +<h2>Dominance<a class="headerlink" href="#dominance" title="Permalink to this headline">¶</a></h2> +<p>Dominance is a mechanism to enable dynamic bodies to dominate each-other. Dominance effectively imbues the dominant body in a pair with infinite mass. This is a form of local mass modification within the constraint solver and, as such, can override the mass of one of the bodies in a pair. Similar effects can be achieved through local mass modification in contact modification but dominance has the advantage of being handled automatically within the SDK so does not incur the additional memory and performance overhead of contact modification.</p> +<p>Each actor must be assigned a dominance group ID. This is a 5-bit value in the range [0, 31]. As such, you are restricted to at-most 32 dominance groups. By default, all bodies are placed in dominance group 0. An actor can be assigned to a dominance group using the following method on PxActor:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">setDominanceGroup</span><span class="p">(</span><span class="n">PxDominanceGroup</span> <span class="n">dominanceGroup</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>Dominance is defined by 2 real numbers in the following struct:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">PxDominanceGroupPair</span> +<span class="p">{</span> + <span class="n">PxDominanceGroupPair</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">a</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">b</span><span class="p">)</span> + <span class="o">:</span> <span class="n">dominance0</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="n">dominance1</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="p">{}</span> + <span class="n">PxReal</span> <span class="n">dominance0</span><span class="p">;</span> + <span class="n">PxReal</span> <span class="n">dominance1</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>And dominance between two dominance groups can be configured using the following method on PxScene:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">setDominanceGroupPair</span><span class="p">(</span><span class="n">PxDominanceGroup</span> <span class="n">group1</span><span class="p">,</span> <span class="n">PxDominanceGroup</span> <span class="n">group2</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxDominanceGroupPair</span><span class="o">&</span> <span class="n">dominance</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>The user can define 3 different states for a given PxDominanceGroupPair: +* 1 : 1. This indicates that both bodies have equal dominance. This is the default behavior. +* 1 : 0. This indicates that body B dominates body A. +* 0 : 1. This indicates that body A dominates body B.</p> +<p>Any values other than 0 and 1 are not valid in a PxDominanceGroupPair. Assigning 0 to both sides of the PxDominanceGroupPair is also invalid. These values can be considered to be scales applied to the bodies' respective inverse mass and inverse inertia. A dominance value of 0 would therefore equate to an infinite mass body.</p> +<p>The following example sets two actors, actorA and actorB, into different dominance groups and configures the dominance group to make actorA dominate actorB:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">actorA</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-></span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">actorB</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-></span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> + +<span class="n">actorA</span><span class="o">-></span><span class="n">setDominanceGroup</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> +<span class="n">actorB</span><span class="o">-></span><span class="n">setDominanceGroup</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> + +<span class="n">mScene</span><span class="o">-></span><span class="n">setDominanceGroupPair</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">PxDominanceGroupPair</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">1.f</span><span class="p">));</span> +</pre></div> +</div> +<p>Dominance values will not affect joints. Local mass modification on joints must be performed using the following methods on PxJoint:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvMassScale0</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invMassScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvMassScale1</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invMassScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvInertiaScale0</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invInertiaScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="k">virtual</span> <span class="kt">void</span> <span class="n">setInvInertiaScale1</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">invInertiaScale</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +</pre></div> +</div> +<p>As previously mentioned, dominance does not permit values other than 0 or 1 and any dominance values are applied uniformly to both the inverse mass and inverse inertia. Joints and contacts through contact modification permit defining separate inverse mass and inverse inertia scales, which accept any values within the range [0, PX_MAX_REAL] so can be used to achieve a wider range of effects than dominance can.</p> +<p>Dominance can produce some very peculiar results if misused. For example, given bodies A, B and C configured in the following way:</p> +<ul class="simple"> +<li>Body A dominates body B</li> +<li>Body B dominance body C</li> +<li>Body C dominates body A</li> +</ul> +<p>In this situation, body A cannot push body C directly. However, it can push body C if it pushes body B into body C.</p> +</div> +<div class="section" id="solver-iterations"> +<h2>Solver Iterations<a class="headerlink" href="#solver-iterations" title="Permalink to this headline">¶</a></h2> +<p>When the motion of a rigid body is constrained either by contacts or joints, the constraint solver comes into play. The solver satisfies the constraints on the bodies by iterating over all the constraints restricting the motion of the body a certain number of times. The more iterations, the more accurate the results become. The solver iteration count defaults to 4 position iterations and 1 velocity iteration. Those counts may be set individually for each body using the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxRigidDynamic</span><span class="o">::</span><span class="n">setSolverIterationCounts</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">minPositionIters</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">minVelocityIters</span><span class="p">);</span> +</pre></div> +</div> +<p>Typically it is only necessary to significantly increase these values for objects with lots of joints and a small tolerance for joint error. If you find a need to use a setting higher than 30, you may wish to reconsider the configuration of your simulation.</p> +<p>The solver groups contacts into friction patches; friction patches are groups of contacts which share the same materials and have similar contact normals. However, the solver permits a maximum of 32 friction patches per contact manager (pair of shapes). If more than 32 friction patches are produced, which may be due to very complex collision geometry or very large contact offsets, the solver will ignore the remaining friction patches. A warning will be issues in checked/debug builds when this happens.</p> +</div> +<div class="section" id="immediate-mode"> +<h2>Immediate Mode<a class="headerlink" href="#immediate-mode" title="Permalink to this headline">¶</a></h2> +<p>In addition to simulation using a PxScene, PhysX offers a low-level simulation API called "immediate mode". This provides an API to access the low-level contact generation and constraint solver. This approach currently supports only CPU rigid bodies and does not support articulations, clothing or particles.</p> +<p>The immediate mode API is defined in PxImmediateMode.h and there is a Snippet demonstrating its usage in "SnippetImmediateMode".</p> +<p>The API provides a function to perform contact generation:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxGenerateContacts</span><span class="p">(</span><span class="k">const</span> <span class="n">PxGeometry</span><span class="o">*</span> <span class="n">geom0</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxGeometry</span><span class="o">*</span> <span class="n">geom1</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">*</span> <span class="n">pose0</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxTransform</span><span class="o">*</span> <span class="n">pose1</span><span class="p">,</span> <span class="n">PxCache</span><span class="o">*</span> <span class="n">contactCache</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbPairs</span><span class="p">,</span> <span class="n">PxContactRecorder</span><span class="o">&</span> <span class="n">contactRecorder</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxReal</span> <span class="n">contactDistance</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">meshContactMargin</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">toleranceLength</span><span class="p">,</span> <span class="n">PxCacheAllocator</span><span class="o">&</span> <span class="n">allocator</span><span class="p">);</span> +</pre></div> +</div> +<p>This function takes a set of pairs of PxGeometry objects located at specific poses and performs collision detection between the pairs. If the pair of geometries collide, contacts are generated, which are reported to contactRecorder. In addition, information may be cached in contactCache to accelerate future queries between these pairs of geometries. Any memory required for this cached information will be allocated using "allocator".</p> +<p>In addition, the immediate mode provides APIs for the constraint solver. These include functions to create bodies used by the solver:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxConstructSolverBodies</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRigidBodyData</span><span class="o">*</span> <span class="n">inRigidData</span><span class="p">,</span> <span class="n">PxSolverBodyData</span><span class="o">*</span> <span class="n">outSolverBodyData</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBodies</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">gravity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">);</span> + +<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxConstructStaticSolverBody</span><span class="p">(</span><span class="k">const</span> <span class="n">PxTransform</span><span class="o">&</span> <span class="n">globalPose</span><span class="p">,</span><span class="n">PxSolverBodyData</span><span class="o">&</span> <span class="n">solverBodyData</span><span class="p">);</span> +</pre></div> +</div> +<p>In addition to constructing the bodies, PxConstraintSolverBodies also integrates the provided gravitational acceleration into the bodies velocities.</p> +<p>The following function is optional and is used to batch constraints:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="n">PxU32</span> <span class="nf">PxBatchConstraints</span><span class="p">(</span><span class="n">PxSolverConstraintDesc</span><span class="o">*</span> <span class="n">solverConstraintDescs</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbConstraints</span><span class="p">,</span> <span class="n">PxSolverBody</span><span class="o">*</span> <span class="n">solverBodies</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">nbBodies</span><span class="p">,</span> <span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">outBatchHeaders</span><span class="p">,</span> + <span class="n">PxSolverConstraintDesc</span><span class="o">*</span> <span class="n">outOrderedConstraintDescs</span><span class="p">);</span> +</pre></div> +</div> +<p>Batching constraints reorders the provided constraints and produces batchHeaders, which can be used by the solver to accelerate constraint solving by grouping together independent constraints and solving them in parallel using multiple lanes in SIMD registers. This process is entirely optional and can bypassed if not desired. Note that this will change the order in which constraints are processed, which can change the outcome of the solver.</p> +<p>The following methods is provided to create contact constraints:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateContactConstraints</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeader</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbHeaders</span><span class="p">,</span> <span class="n">PxSolverContactDesc</span><span class="o">*</span> <span class="n">contactDescs</span><span class="p">,</span> + <span class="n">PxConstraintAllocator</span><span class="o">&</span> <span class="n">allocator</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">bounceThreshold</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">frictionOffsetThreshold</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">correlationDistance</span><span class="p">);</span> +</pre></div> +</div> +<p>This method can be provided with the contacts produced by PxGenerateContacts or by contacts produced by application-specific contact generation approaches.</p> +<p>The following methods are provided to create joint constraints:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateJointConstraints</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeader</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbHeaders</span><span class="p">,</span> <span class="n">PxSolverConstraintPrepDesc</span><span class="o">*</span> <span class="n">jointDescs</span><span class="p">,</span> <span class="n">PxConstraintAllocator</span><span class="o">&</span> <span class="n">allocator</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">);</span> + +<span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">bool</span> <span class="nf">PxCreateJointConstraintsWithShaders</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeader</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBatchHeaders</span><span class="p">,</span> <span class="n">PxConstraint</span><span class="o">**</span> <span class="n">constraints</span><span class="p">,</span> <span class="n">PxSolverConstraintPrepDesc</span><span class="o">*</span> <span class="n">jointDescs</span><span class="p">,</span> <span class="n">PxConstraintAllocator</span><span class="o">&</span> <span class="n">allocator</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">dt</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">invDt</span><span class="p">);</span> +</pre></div> +</div> +<p>The methods provide a mechanism for the application to define joint rows or for the application to make use of PhysX PxConstraint objects, which create the constraint rows.</p> +<p>The following method solves the constraints:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="n">PX_PHYSX_CORE_API</span> <span class="kt">void</span> <span class="nf">PxSolveConstraints</span><span class="p">(</span><span class="n">PxConstraintBatchHeader</span><span class="o">*</span> <span class="n">batchHeaders</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbBatchHeaders</span><span class="p">,</span> <span class="n">PxSolverConstraintDesc</span><span class="o">*</span> <span class="n">solverConstraintDescs</span><span class="p">,</span> <span class="n">PxSolverBody</span><span class="o">*</span> <span class="n">solverBodies</span><span class="p">,</span> + <span class="n">PxVec3</span><span class="o">*</span> <span class="n">linearMotionVelocity</span><span class="p">,</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">angularMotionVelocity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbSolverBodies</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbPositionIterations</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbVelocityIterations</span><span class="p">);</span> +</pre></div> +</div> +<p>This method performs all required position and velocity iterations and updates the objects' delta velocities and motion velocities, which are stored in PxSolverBody and linear/angularMotionVelocity respectively.</p> +<p>The following method is provided to integrate the bodies' final poses and update the bodies' velocities to reflect the motion produced by the constraint solver.</p> +<p>An example of how the immediate mode can be used is provided in SnippetImmediateMode.</p> +</div> +<div class="section" id="enhanced-determinism"> +<h2>Enhanced Determinism<a class="headerlink" href="#enhanced-determinism" title="Permalink to this headline">¶</a></h2> +<p>PhysX provides limited deterministic simulation. Specifically, the results of the simulation will be identical between runs if simulating the exact same scene (same actors inserted in the same order) using the same time-stepping scheme and same PhysX release running on the same platform. The simulation behavior is not influenced by the number of worker threads that are used.</p> +<p>However, the results of the simulation can change if actors are inserted in a different order. In addition, the overall behavior of the simulation can change if additional actors are added or if some actors are removed from the scene. This means that the simulation of a particular collection of actors can change depending on whether other actors are present in the scene or not, irrespective of whether these actors actually interact with the collection of actors. This behavioral property is usually tolerable but there are circumstances in which it is not acceptable.</p> +<p>To overcome this issue, PhysX provides a flag: PxSceneFlag::eENABLE_ENHANCED_DETERMINISM, which provides additional levels of determinism. Specifically, provided the application inserts the actors in a deterministic order, with this flag raised, the simulation of an island will be identical regardless of any other islands in the scene. However, this mode sacrifices some performance to ensure this additional determinism.</p> +</div> +<div class="section" id="axis-locking"> +<h2>Axis locking<a class="headerlink" href="#axis-locking" title="Permalink to this headline">¶</a></h2> +<p>It is possible to restrict motion along or around specific world-space axes in PhysX using PxRigidDynamicLockFlag. For example, the below code snippet demonstrates how to restrict a PxRigidDynamic to two dimensional simulation. In this case, we permit the PxRigidDynamic to rotate only around the Z-axis and to translate only along the X- and Y- axes:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dyn</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">0.f</span><span class="p">,</span> <span class="mf">2.5f</span><span class="p">,</span> <span class="mf">0.f</span><span class="p">)));</span> + +<span class="p">...</span> + +<span class="c1">//Lock the motion</span> +<span class="n">dyn</span><span class="o">-></span><span class="n">setRigidDynamicLockFlags</span><span class="p">(</span><span class="n">PxRigidDynamicLockFlag</span><span class="o">::</span><span class="n">eLOCK_LINEAR_Z</span> <span class="o">|</span> <span class="n">PxRigidDynamicLockFlag</span><span class="o">::</span><span class="n">eLOCK_ANGULAR_X</span> <span class="o">|</span> <span class="n">PxRigidDynamicLockFlag</span><span class="o">::</span><span class="n">eLOCK_ANGULAR_Y</span><span class="p">);</span> +</pre></div> +</div> +<p>It is legal to restrict movement or rotation around any combination of the 6 degrees of freedom.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Rigid Body Dynamics</a><ul> +<li><a class="reference internal" href="#velocity">Velocity</a></li> +<li><a class="reference internal" href="#mass-properties">Mass Properties</a></li> +<li><a class="reference internal" href="#applying-forces-and-torques">Applying Forces and Torques</a></li> +<li><a class="reference internal" href="#gravity">Gravity</a></li> +<li><a class="reference internal" href="#friction-and-restitution">Friction and Restitution</a></li> +<li><a class="reference internal" href="#sleeping">Sleeping</a><ul> +<li><a class="reference internal" href="#sleep-state-change-events">Sleep state change events</a></li> +</ul> +</li> +<li><a class="reference internal" href="#kinematic-actors">Kinematic Actors</a></li> +<li><a class="reference internal" href="#active-transforms">Active Transforms</a></li> +<li><a class="reference internal" href="#active-actors">Active Actors</a></li> +<li><a class="reference internal" href="#dominance">Dominance</a></li> +<li><a class="reference internal" href="#solver-iterations">Solver Iterations</a></li> +<li><a class="reference internal" href="#immediate-mode">Immediate Mode</a></li> +<li><a class="reference internal" href="#enhanced-determinism">Enhanced Determinism</a></li> +<li><a class="reference internal" href="#axis-locking">Axis locking</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="RigidBodyCollision.html" + title="previous chapter">Rigid Body Collision</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Simulation.html" + title="next chapter">Simulation</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" /> + <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="Simulation.html" title="Simulation" + >next</a></li> + <li class="right" > + <a href="RigidBodyCollision.html" title="Rigid Body Collision" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyOverview.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyOverview.html new file mode 100644 index 00000000..565fca17 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/RigidBodyOverview.html @@ -0,0 +1,203 @@ +<!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>Rigid Body Overview — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Rigid Body Collision" href="RigidBodyCollision.html" /> + <link rel="prev" title="Geometry" href="Geometry.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="RigidBodyCollision.html" title="Rigid Body Collision" + accesskey="N">next</a></li> + <li class="right" > + <a href="Geometry.html" title="Geometry" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="rigid-body-overview"> +<span id="rigidbodyoverview"></span><h1>Rigid Body Overview<a class="headerlink" href="#rigid-body-overview" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This chapter will introduce the fundamentals of simulating rigid body dynamics using the NVIDIA PhysX engine.</p> +</div> +<div class="section" id="rigid-body-object-model"> +<h2>Rigid Body Object Model<a class="headerlink" href="#rigid-body-object-model" title="Permalink to this headline">¶</a></h2> +<p>PhysX uses a hierarchical rigid body object/actor model, which looks like this:</p> +<img alt="../_images/ObjectModel.png" src="../_images/ObjectModel.png" /> +<table border="1" class="docutils"> +<colgroup> +<col width="12%" /> +<col width="16%" /> +<col width="72%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head">Class</th> +<th class="head">Extends</th> +<th class="head">Functionality</th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><em>PxBase</em></td> +<td>N/A</td> +<td>Reflection/querying object types.</td> +</tr> +<tr class="row-odd"><td><em>PxActor</em></td> +<td>PxBase</td> +<td>Actor name, actor flags, dominance, clients, aggregates, query world bounds.</td> +</tr> +<tr class="row-even"><td><em>PxRigidActor</em></td> +<td>PxActor</td> +<td>Shapes and transforms.</td> +</tr> +<tr class="row-odd"><td><em>PxRigidBody</em></td> +<td>PxRigidActor</td> +<td>Mass, inertia, velocities, body flags.</td> +</tr> +<tr class="row-even"><td><em>PxRigidStatic</em></td> +<td>PxRigidActor</td> +<td>Interface for static body in the scene. This kind of body has implicit infinite mass/inertia.</td> +</tr> +<tr class="row-odd"><td><em>PxRigidDynamic</em></td> +<td>PxRigidBody</td> +<td>Interface for dynamic rigid body in the scene. Introduces support for kinematic targets and object sleeping.</td> +</tr> +<tr class="row-even"><td><em>PxArticulationLink</em></td> +<td>PxRigidBody</td> +<td>Interface for a dynamic rigid body link in a PxArticulation. Introduces support for querying the articulation and adjacent links.</td> +</tr> +<tr class="row-odd"><td><em>PxArticulation</em></td> +<td>PxBase</td> +<td>Defines interface for a PxArticulation. Effectively a contained referencing multiple PxArticualtionLink rigid bodies.</td> +</tr> +</tbody> +</table> +<p>The following diagram shows the relationship between the main types involved in the rigid body pipeline:</p> +<img alt="../_images/RigidBodyOverview.PNG" src="../_images/RigidBodyOverview.PNG" /> +</div> +<div class="section" id="the-simulation-loop"> +<h2>The Simulation Loop<a class="headerlink" href="#the-simulation-loop" title="Permalink to this headline">¶</a></h2> +<p>Now use the method PxScene::simulate() to advance the world forward in time. Here is simplified code from the samples' fixed stepper class:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mAccumulator</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">;</span> +<span class="n">mStepSize</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="k">virtual</span> <span class="kt">bool</span> <span class="nf">advance</span><span class="p">(</span><span class="n">PxReal</span> <span class="n">dt</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">mAccumulator</span> <span class="o">+=</span> <span class="n">dt</span><span class="p">;</span> + <span class="k">if</span><span class="p">(</span><span class="n">mAccumulator</span> <span class="o"><</span> <span class="n">mStepSize</span><span class="p">)</span> + <span class="k">return</span> <span class="nb">false</span><span class="p">;</span> + + <span class="n">mAccumulator</span> <span class="o">-=</span> <span class="n">mStepSize</span><span class="p">;</span> + + <span class="n">mScene</span><span class="o">-></span><span class="n">simulate</span><span class="p">(</span><span class="n">mStepSize</span><span class="p">);</span> + <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This is called from the sample framework whenever the app is done with processing events and is starting to idle. It accumulates elapsed real time until it is greater than a sixtieth of a second, and then calls simulate(), which moves all objects in the scene forward by that interval. This is probably the simplest of very many different ways to deal with time when stepping the simulation forward.</p> +<p>To allow the simulation to finish and return the results, simply call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mScene</span><span class="o">-></span><span class="n">fetchResults</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>True indicates that the simulation should block until it is finished, so that on return the results are guaranteed to be available. When fetchResults completes, any simulation event callback functions that you defined will also be called. See the chapter <a class="reference internal" href="Simulation.html#callbacks"><em>Callback Sequence</em></a>.</p> +<p>It is possible to read and write from the scene during simulation. The samples take advantage of this to perform rendering work in parallel with physics. Until fetchResults() returns, the results of the current simulation step are not available. So running rendering in parallel with simulation renders the actors as they were when simulate() was called. After fetchResults() returns, all these functions will return the new, post-simulate state. See the chapter <a class="reference internal" href="Threading.html#threading"><em>Threading</em></a> for more details about reading and writing while the simulation is running.</p> +<p>For the human eye to perceive animated motion as smooth, use at least twenty discrete frames per second, with each frame corresponding to a physics time step. To have smooth, realistic simulation of more complex physical scenes, use at least fifty frames per second.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">If you are making a real-time interactive simulation, you may be tempted to take different sized time steps which correspond to the amount of real time that has elapsed since the last simulation frame. Be very careful if you do this, rather than taking constant-sized time steps: The simulation code is sensitive to both very small and large time steps, and also to too much variation between time steps. In these cases it will likely produce jittery simulation.</p> +</div> +<p>See <a class="reference internal" href="Simulation.html#simulation-memory"><em>Simulation memory</em></a> for details of how memory is used in simulation.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Rigid Body Overview</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#rigid-body-object-model">Rigid Body Object Model</a></li> +<li><a class="reference internal" href="#the-simulation-loop">The Simulation Loop</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Geometry.html" + title="previous chapter">Geometry</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="RigidBodyCollision.html" + title="next chapter">Rigid Body Collision</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" /> + <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="RigidBodyCollision.html" title="Rigid Body Collision" + >next</a></li> + <li class="right" > + <a href="Geometry.html" title="Geometry" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/SceneQueries.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/SceneQueries.html new file mode 100644 index 00000000..694fc898 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/SceneQueries.html @@ -0,0 +1,687 @@ +<!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>Scene Queries — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Vehicles" href="Vehicles.html" /> + <link rel="prev" title="Spatial Queries" href="SpatialQueries.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Vehicles.html" title="Vehicles" + accesskey="N">next</a></li> + <li class="right" > + <a href="SpatialQueries.html" title="Spatial Queries" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="scene-queries"> +<span id="scenequeries"></span><h1>Scene Queries<a class="headerlink" href="#scene-queries" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>PhysX provides methods in PxScene to perform collision queries against actors and attached shapes in the scene. There are three types of queries: raycasts, sweeps and overlaps, and each can return either a single result, or multiple results. Broadly speaking, each query traverses a culling structure containing the scene objects, performs a precise test using the GeometryQuery functions (see <a class="reference internal" href="GeometryQueries.html#geometryqueries"><em>Geometry Queries</em></a>), and accumulates the results. Filtering may occur before or after precise testing.</p> +<p>The scene uses two different query structures, one for <em>PxRigidStatic</em> actors, and the other for <em>PxRigidBody</em> actors (<em>PxRigidDynamic</em> and <em>PxArticulationLink</em>.) The two structures may be configured to use different culling implementations depending on the desired speed/space characteristics (see <a class="reference internal" href="#pxpruningstructuretype"><em>PxPruningStructureType</em></a>.)</p> +</div> +<div class="section" id="basic-queries"> +<h2>Basic queries<a class="headerlink" href="#basic-queries" title="Permalink to this headline">¶</a></h2> +<div class="section" id="raycasts"> +<h3>Raycasts<a class="headerlink" href="#raycasts" title="Permalink to this headline">¶</a></h3> +<p>A <em>PxScene::raycast()</em> query intersects a user-defined ray with the whole scene. +The simplest use case for a raycast() query is to find the closest hit along a given ray as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> +<span class="n">PxRaycastBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Raycast results</span> + +<span class="c1">// Raycast against all static & dynamic objects (no filtering)</span> +<span class="c1">// The main result from this call is the closest hit, stored in the 'hit.block' structure</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">status</span><span class="p">)</span> + <span class="n">applyDamage</span><span class="p">(</span><span class="n">hit</span><span class="p">.</span><span class="n">block</span><span class="p">.</span><span class="n">position</span><span class="p">,</span> <span class="n">hit</span><span class="p">.</span><span class="n">block</span><span class="p">.</span><span class="n">normal</span><span class="p">);</span> +</pre></div> +</div> +<p>In this code snippet a PxRaycastBuffer object is used to receive results from the raycast query. +A call to raycast() returns true if there was a hit. hit.hadBlock is also set to true if there was a hit. +The distance for raycasts has to be in the [0, inf) range.</p> +<p>Raycasts results include position, normal, hit distance, shape and actor, and a face index with UV coordinates for triangle meshes and heightfields. Before using query results check PxHitFlag::ePOSITION, eNORMAL, eDISTANCE, eUV flags first, as in some cases they are not set.</p> +</div> +<div class="section" id="sweeps"> +<h3>Sweeps<a class="headerlink" href="#sweeps" title="Permalink to this headline">¶</a></h3> +<p>A <em>PxScene::sweep()</em> query is geometrically similar to a raycast(): a PxGeometry shape is swept from a specified initial pose in a direction unitDir with specified maximum length, to find the points of impacts of the geometry with scene objects. The maximum distance for sweeps has to be in the [0, inf) range, and will be clamped by to PX_MAX_SWEEP_DISTANCE, defined in file PxScene.h.</p> +<p>Allowed shapes are box, sphere, capsule and convex.</p> +<p>A PxSweepBuffer object is used to receive results from sweep() queries:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSweepBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Sweep results</span> +<span class="n">PxGeometry</span> <span class="n">sweepShape</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] swept shape</span> +<span class="n">PxTransform</span> <span class="n">initialPose</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] initial shape pose (at distance=0)</span> +<span class="n">PxVec3</span> <span class="n">sweepDirection</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] normalized sweep direction</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">sweep</span><span class="p">(</span><span class="n">sweepShape</span><span class="p">,</span> <span class="n">initialPose</span><span class="p">,</span> <span class="n">sweepDirection</span><span class="p">,</span> <span class="n">sweepDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">);</span> +</pre></div> +</div> +<p>Sweeps results include position, normal, hit distance, shape and actor, and a face index for triangle meshes and heightfields.</p> +</div> +<div class="section" id="overlaps"> +<h3>Overlaps<a class="headerlink" href="#overlaps" title="Permalink to this headline">¶</a></h3> +<p><em>PxScene::overlap()</em> query searches a region enclosed by a specified shape for any overlapping objects in the scene. +The region is specified as a transformed box, sphere, capsule or convex geometry.</p> +<p>A PxOverlapBuffer object is used to receive results from overlap() queries:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxOverlapBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Overlap results</span> +<span class="n">PxGeometry</span> <span class="n">overlapShape</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] shape to test for overlaps</span> +<span class="n">PxTransform</span> <span class="n">shapePose</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] initial shape pose (at distance=0)</span> + +<span class="n">PxOverlapBuffer</span> <span class="n">hit</span><span class="p">;</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">overlap</span><span class="p">(</span><span class="n">overlapShape</span><span class="p">,</span> <span class="n">shapePose</span><span class="p">,</span> <span class="n">hit</span><span class="p">);</span> +</pre></div> +</div> +<p>Overlaps results only include actor/shape and faceIndex since there is no single point of intersection.</p> +</div> +</div> +<div class="section" id="touching-and-blocking-hits"> +<h2>Touching and blocking hits<a class="headerlink" href="#touching-and-blocking-hits" title="Permalink to this headline">¶</a></h2> +<p>For queries with multiple results we distinguish between <em>touching</em> and <em>blocking</em> hits. The choice of whether a hit is touching or blocking is made by the user-implemented filtering logic. Intuitively a blocking hit prevents further progress of a raycast or a sweep along its path, and a touching hit is recorded but allows the ray or sweep to continue. So a multiple-hit query will return the closest blocking hit if one exists, together with any touching hits that are closer. If there are no blocking hits, all touching hits will be returned.</p> +<p>See the <a class="reference internal" href="#queryfiltering"><em>Filtering</em></a> section for details.</p> +</div> +<div class="section" id="query-modes"> +<h2>Query modes<a class="headerlink" href="#query-modes" title="Permalink to this headline">¶</a></h2> +<div class="section" id="closest-hit"> +<h3>Closest hit<a class="headerlink" href="#closest-hit" title="Permalink to this headline">¶</a></h3> +<p>The default mode of operation for all three query types is "closest hit". The query looks for all blocking hits, picks the one with the minimum distance and reports it in the PxHitBuffer::block member.</p> +<ul class="simple"> +<li>For overlap() queries an arbitrary blocking hit is chosen as the reported blocking hit (distance is treated as zero for all overlap() hits).</li> +</ul> +</div> +<div class="section" id="any-hit"> +<h3>Any hit<a class="headerlink" href="#any-hit" title="Permalink to this headline">¶</a></h3> +<p>All three query types can operate in "any hit" mode. This is a performance hint to the query system indicating that there is no need to look +for the closest hit - any hit encountered will do. This mode is most often used for boolean blocking/non-blocking queries. +Performance improvement may be a factor of 3 or more, depending on scenario. +To activate this mode use PxQueryFlag::eANY_HIT filter data flag and set it in PxQueryFilterData object, for instance:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxQueryFilterData</span> <span class="n">fd</span><span class="p">;</span> +<span class="n">fd</span><span class="p">.</span><span class="n">flags</span> <span class="o">|=</span> <span class="n">PxQueryFlag</span><span class="o">::</span><span class="n">eANY_HIT</span><span class="p">;</span> <span class="c1">// note the OR with the default value</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">,</span> + <span class="n">PxHitFlags</span><span class="p">(</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">),</span> <span class="n">fdAny</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="multiple-hits"> +<h3>Multiple hits<a class="headerlink" href="#multiple-hits" title="Permalink to this headline">¶</a></h3> +<p>All three query types (raycast, overlap, sweep) can also report multiple hits with objects in the scene.</p> +<ul class="simple"> +<li>To activate this mode for raycasts use the PxRaycastBuffer constructor with user provided buffer for touching hits.</li> +<li>In this mode all hits default to 'touching' type and are recorded in the PxRaycastBuffer::touches array.</li> +</ul> +<p>For instance:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> + +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">bufferSize</span> <span class="o">=</span> <span class="mi">256</span><span class="p">;</span> <span class="c1">// [in] size of 'hitBuffer'</span> +<span class="n">PxRaycastHit</span> <span class="n">hitBuffer</span><span class="p">[</span><span class="n">bufferSize</span><span class="p">];</span> <span class="c1">// [out] User provided buffer for results</span> +<span class="n">PxRaycastBuffer</span> <span class="nf">buf</span><span class="p">(</span><span class="n">hitBuffer</span><span class="p">,</span> <span class="n">bufferSize</span><span class="p">);</span> <span class="c1">// [out] Blocking and touching hits stored here</span> + +<span class="c1">// Raycast against all static & dynamic objects (no filtering)</span> +<span class="c1">// The main result from this call are all hits along the ray, stored in 'hitBuffer'</span> +<span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">buf</span><span class="p">.</span><span class="n">nbTouches</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">animateLeaves</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">touches</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> +</pre></div> +</div> +<p>The same mechanism is used for overlaps (use PxOverlapBuffer with PxOverlapHit[]) and sweeps (PxSweepBuffer with PxSweepHit[]).</p> +</div> +<div class="section" id="multiple-hits-with-blocking-hit"> +<h3>Multiple hits with blocking hit<a class="headerlink" href="#multiple-hits-with-blocking-hit" title="Permalink to this headline">¶</a></h3> +<p>In the snippet for multiple hits above we only expected touching hits. If a blocking hit was encountered along with touching hits, it will be reported in PxHitBuffer::block member, and the touch buffer will contain only touching hits which are closer. This combination is useful in scenarios such as bullets going through windows (breaking them on their way) or leaves of a tree (making them rustle) until they hit a blocking object (a concrete wall):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// same initialization code as in the snippet for multiple hits</span> +<span class="kt">bool</span> <span class="n">hadBlockingHit</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="n">hadBlockingHit</span><span class="p">)</span> + <span class="n">drawWallDecal</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">block</span><span class="p">);</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">buf</span><span class="p">.</span><span class="n">nbTouches</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">assert</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">touches</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">distance</span> <span class="o"><=</span> <span class="n">buf</span><span class="p">.</span><span class="n">block</span><span class="p">.</span><span class="n">distance</span><span class="p">);</span> + <span class="n">animateLeaves</span><span class="p">(</span><span class="n">buf</span><span class="p">.</span><span class="n">touches</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> +<span class="p">}</span> +</pre></div> +</div> +<ul class="simple"> +<li>By default, hits are assumed to be touching when a touch buffer is provided, and the filter callback should return PxQueryHitType::eBLOCK +to denote that a hit is blocking. See <a class="reference internal" href="#queryfiltering"><em>Filtering</em></a> for details.</li> +<li>For overlap() queries all touching hits will be recorded even if a blocking hit was encountered and PxQueryFlag::eNO_BLOCK flag is set.</li> +</ul> +</div> +</div> +<div class="section" id="filtering"> +<span id="queryfiltering"></span><h2>Filtering<a class="headerlink" href="#filtering" title="Permalink to this headline">¶</a></h2> +<p>Filtering controls how shapes are excluded from scene query results and how results are reported. +All three query types support the following filtering parameters:</p> +<ul class="simple"> +<li>a <em>PxQueryFilterData</em> structure, containing both <em>PxQueryFlags</em> and <em>PxFilterData</em></li> +<li>an optional <em>PxQueryFilterCallback</em></li> +</ul> +<div class="section" id="pxqueryflag-estatic-pxqueryflag-edynamic"> +<h3>PxQueryFlag::eSTATIC, PxQueryFlag::eDYNAMIC<a class="headerlink" href="#pxqueryflag-estatic-pxqueryflag-edynamic" title="Permalink to this headline">¶</a></h3> +<p><em>PxQueryFlag::eSTATIC</em> and <em>PxQueryFlag::eDYNAMIC</em> flags control whether the query should include shapes from the static and/or dynamic query structures. +This is the most efficient way to filter out all static/dynamic shapes. +For example an explosion effect that applies forces to all dynamics in a region could use a spherical <em>overlap</em> query, +and only the <em>PxQueryFlag::eDYNAMIC</em> flag to exclude all statics since forces cannot be applied to static objects. +By default both statics and dynamics are included in query results.</p> +<p>For instance:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> +<span class="n">PxRaycastBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Raycast results</span> + +<span class="c1">// [in] Define filter for static objects only</span> +<span class="n">PxQueryFilterData</span> <span class="nf">filterData</span><span class="p">(</span><span class="n">PxQueryFlag</span><span class="o">::</span><span class="n">eSTATIC</span><span class="p">);</span> + +<span class="c1">// Raycast against static objects only</span> +<span class="c1">// The main result from this call is the boolean 'status'</span> +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">,</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">,</span> <span class="n">filterData</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="pxqueryflag-eprefilter-pxqueryflag-epostfilter"> +<h3>PxQueryFlag::ePREFILTER, PxQueryFlag::ePOSTFILTER<a class="headerlink" href="#pxqueryflag-eprefilter-pxqueryflag-epostfilter" title="Permalink to this headline">¶</a></h3> +<p>Scene queries are performed in three phases: broad phase, midphase and narrow phase.</p> +<ul class="simple"> +<li>Broad phase traverses the global scene spatial partitioning structure to find the candidates for mid and narrow phases.</li> +<li>midphase traverses the triangle mesh and heightfield internal culling structures, to find a smaller subset of the triangles +in a mesh reported by the broad phase.</li> +<li>Narrow phase performs exact intersection tests (ray test for raycast() queries, and exact sweep shape tests +or overlap tests for sweep() and overlap() queries).</li> +</ul> +<p>To implement custom filtering in queries, set the <em>PxQueryFlag::ePREFILTER</em> and/or <em>PxQueryFlag::ePOSTFILTER</em> flags and subclass <em>PxQueryFilterCallback</em> with the required filtering logic.</p> +<ul class="simple"> +<li>Pre-filtering happens before midphase and narrow phase and allows shapes to be efficiently discarded before the potentially +expensive exact collision test. These tests are more expensive for triangle meshes, heightfields, convexes and most sweeps than raycast +and overlap tests involving only simple shapes (such as spheres, capsules and boxes.)</li> +<li>Post-filtering happens after the narrow phase test and can therefore use the results of the test (such as PxRaycastHit.position) +to determine whether a hit should be discarded or not. These results can be accessed via the <em>hit</em> input argument to the post-filtering callback (PxQueryFilterCallback::postFilter). Use e.g. static_cast<PxRaycastHit&>(hit), access data specific to a raycast query, and similarly for overlaps (PxOverlapHit) and sweeps (PxSweepHit.)</li> +</ul> +<p>The implementation of a filtering callback returns a <em>PxQueryHitType</em> result.</p> +<ul class="simple"> +<li><em>eNONE</em> indicates that the hit should be discarded.</li> +<li><em>eBLOCK</em> indicates that the hit is blocking.</li> +<li><em>eTOUCH</em> indicates that the hit is touching.</li> +</ul> +<p>Whenever a raycast(), sweep() or overlap() query was called with non-zero PxHitCallback::nbTouches and PxHitCallback::touches parameters, eTOUCH type hits that are no further (touchDistance <= blockDistance) than the closest eBLOCK type hit, will be reported. For example, to record all hits from a raycast query, always return eTOUCH.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Returning eTOUCH from a filter callback requires the hit buffer query parameter to have a non-zero ::touches array, otherwise PhysX will generate an error in checked builds and discard any touching hits.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">eBLOCK should not be returned from user filters for overlap(). Doing so will result in undefined behavior, and a warning will be issued. If the PxQueryFlag::eNO_BLOCK flag is set, the eBLOCK will instead be automatically converted to an eTOUCH and the warning suppressed.</p> +</div> +</div> +<div class="section" id="pxqueryflag-eany-hit"> +<h3>PxQueryFlag::eANY_HIT<a class="headerlink" href="#pxqueryflag-eany-hit" title="Permalink to this headline">¶</a></h3> +<p>Use this flag to force the query to report the first encountered hit (which may not be the closest) as a blocking hit. +Performance may be more than three times faster, depending on the scenario. Best gains can be expected for long raycasts/sweeps +with a nearby intersecting object, or overlaps with multiple intersecting objects.</p> +<ul class="simple"> +<li>Also see PxHitFlag::eMESH_ANY</li> +</ul> +</div> +<div class="section" id="pxqueryflag-eno-block"> +<h3>PxQueryFlag::eNO_BLOCK<a class="headerlink" href="#pxqueryflag-eno-block" title="Permalink to this headline">¶</a></h3> +<p>Use this flag when you want to override the eBLOCK value returned from filters to eTOUCH or in cases when no blocking hits are +expected (in this case this flag serves as a performance hint.) All hits will then be reported as touching regardless of the filter callback return value. +The hit callback/buffer object provided to the query is required to have a non-zero +<em>PxHitBuffer::touches</em> buffer when this flag is used. Significant performance gains should only be expected for scenarios where the touching hit buffer overflows.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">this flag overrides the return value from pre and post-filter functions, so hits that were previously returned as blocking will instead be returned as touching.</p> +</div> +</div> +<div class="section" id="pxfilterdata-fixed-function-filtering"> +<h3>PxFilterData fixed function filtering<a class="headerlink" href="#pxfilterdata-fixed-function-filtering" title="Permalink to this headline">¶</a></h3> +<p>A fast, fixed-function filter is provided by <em>PxFilterData</em>, a 4*32-bit bitmask used by the built-in filtering equation. +Each shape has a bitmask (set via PxShape::setQueryFilterData()), and the query also has a bitmask.</p> +<p>The query data is used differently by batched and unbatched queries (see below for batched queries). For unbatched queries, the following rules are applied:</p> +<ul class="simple"> +<li>If the query's bitmask is all zeroes, custom filtering and intersection testing proceed as normal.</li> +<li>Otherwise, if the bitwise-AND value of the query's bitmask and the shape's bitmask is zero, the shape is skipped</li> +</ul> +<p>Or in other words:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxU32</span> <span class="n">keep</span> <span class="o">=</span> <span class="p">(</span><span class="n">query</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">object</span><span class="p">.</span><span class="n">word0</span><span class="p">)</span> + <span class="o">|</span> <span class="p">(</span><span class="n">query</span><span class="p">.</span><span class="n">word1</span> <span class="o">&</span> <span class="n">object</span><span class="p">.</span><span class="n">word1</span><span class="p">)</span> + <span class="o">|</span> <span class="p">(</span><span class="n">query</span><span class="p">.</span><span class="n">word2</span> <span class="o">&</span> <span class="n">object</span><span class="p">.</span><span class="n">word2</span><span class="p">)</span> + <span class="o">|</span> <span class="p">(</span><span class="n">query</span><span class="p">.</span><span class="n">word3</span> <span class="o">&</span> <span class="n">object</span><span class="p">.</span><span class="n">word3</span><span class="p">);</span> +</pre></div> +</div> +<p>This hardcoded equation can provide simple filtering while avoiding the function call overhead of the filtering callback. For example, to emulate the behavior of PhysX 2 active groups, define the groups as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">ActiveGroup</span> +<span class="p">{</span> + <span class="n">GROUP1</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">0</span><span class="p">),</span> + <span class="n">GROUP2</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">1</span><span class="p">),</span> + <span class="n">GROUP3</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">2</span><span class="p">),</span> + <span class="n">GROUP4</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">3</span><span class="p">),</span> + <span class="p">...</span> +<span class="p">};</span> +</pre></div> +</div> +<p>When shapes are created, they can be assigned to the a group, for example GROUP1:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">;</span> <span class="c1">// Previously created shape</span> + +<span class="n">PxFilterData</span> <span class="n">filterData</span><span class="p">;</span> +<span class="n">filterData</span><span class="p">.</span><span class="n">word0</span> <span class="o">=</span> <span class="n">GROUP1</span><span class="p">;</span> +<span class="n">shape</span><span class="o">-></span><span class="n">setQueryFilterData</span><span class="p">(</span><span class="n">filterData</span><span class="p">);</span> +</pre></div> +</div> +<p>Or to multiple groups, for example GROUP1 and GROUP3:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxShape</span><span class="o">*</span> <span class="n">shape</span><span class="p">;</span> <span class="c1">// Previously created shape</span> + +<span class="n">PxFilterData</span> <span class="n">filterData</span><span class="p">;</span> +<span class="n">filterData</span><span class="p">.</span><span class="n">word0</span> <span class="o">=</span> <span class="n">GROUP1</span><span class="o">|</span><span class="n">GROUP3</span><span class="p">;</span> +<span class="n">shape</span><span class="o">-></span><span class="n">setQueryFilterData</span><span class="p">(</span><span class="n">filterData</span><span class="p">);</span> +</pre></div> +</div> +<p>When performing a scene query, select which groups are active for the query - for example GROUP2 and GROUP3 - as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> +<span class="n">PxRaycastBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Raycast results</span> + +<span class="c1">// [in] Define what parts of PxRaycastHit we're interested in</span> +<span class="k">const</span> <span class="n">PxHitFlags</span> <span class="n">outputFlags</span> <span class="o">=</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDISTANCE</span> <span class="o">|</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">ePOSITION</span> <span class="o">|</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eNORMAL</span><span class="p">;</span> + +<span class="c1">// [in] Raycast against GROUP2 and GROUP3</span> +<span class="n">PxQueryFilterData</span> <span class="n">filterData</span> <span class="o">=</span> <span class="n">PxQueryFilterData</span><span class="p">();</span> +<span class="n">filterData</span><span class="p">.</span><span class="n">data</span><span class="p">.</span><span class="n">word0</span> <span class="o">=</span> <span class="n">GROUP2</span><span class="o">|</span><span class="n">GROUP3</span><span class="p">;</span> + +<span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">,</span> <span class="n">outputFlags</span><span class="p">,</span> <span class="n">filterData</span><span class="p">);</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="user-defined-hit-callbacks-for-unbounded-results"> +<h2>User defined hit callbacks for unbounded results<a class="headerlink" href="#user-defined-hit-callbacks-for-unbounded-results" title="Permalink to this headline">¶</a></h2> +<p>Queries can sometimes return a very large number of results (for example, queries with very large objects or in areas with high object density), and +it can be prohibitively expensive to reserve a sufficiently large memory buffer. The classes PxRaycastCallback, PxSweepCallback and PxOverlapCallback +provide efficient callback based solutions for such scenarios. For instance a <em>raycast</em> query with a PxRaycastCallback callback will return all touch hits +via multiple virtual PxHitCallback::processTouches() callbacks:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">UserCallback</span> <span class="o">:</span> <span class="n">PxRaycastCallback</span> +<span class="p">{</span> + <span class="n">UserData</span> <span class="n">data</span><span class="p">;</span> + <span class="k">virtual</span> <span class="n">PxAgain</span> <span class="nf">processTouches</span><span class="p">(</span><span class="k">const</span> <span class="n">PxRaycastHit</span><span class="o">*</span> <span class="n">buffer</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">nbHits</span><span class="p">)</span> + <span class="c1">// This callback can be issued multiple times and can be used</span> + <span class="c1">// to process an unbounded number of touching hits.</span> + <span class="c1">// Each reported touching hit in buffer is guaranteed to be closer than</span> + <span class="c1">// the final block hit after the query has fully executed.</span> + <span class="p">{</span> + <span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">nbHits</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">animateLeaves</span><span class="p">(</span><span class="n">buffer</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">data</span><span class="p">);</span> + <span class="p">}</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">finalizeQuery</span><span class="p">()</span> + <span class="p">{</span> + <span class="n">drawWallDecal</span><span class="p">(</span><span class="k">this</span><span class="o">-></span><span class="n">block</span><span class="p">,</span> <span class="n">data</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">};</span> + +<span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> + +<span class="n">UserCallback</span> <span class="n">cb</span><span class="p">;</span> <span class="n">cb</span><span class="p">.</span><span class="n">data</span> <span class="o">=</span> <span class="p">...;</span> +<span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">cb</span><span class="p">);</span> <span class="c1">// see UserCallback::processTouches</span> +</pre></div> +</div> +<p>In this code snippet the raycast() query will potentially invoke processTouches multiple times, with all touching hits already +clipped to the globally nearest blocking hit.</p> +<ul class="simple"> +<li>Note that the query can be up to twice as expensive in case all eTOUCH results do not fit in the provided touches buffer +and a blocking hit was also found.</li> +<li>Also see PxQueryFlag::eNO_BLOCK</li> +</ul> +</div> +<div class="section" id="batched-queries"> +<span id="id1"></span><h2>Batched queries<a class="headerlink" href="#batched-queries" title="Permalink to this headline">¶</a></h2> +<p>PhysX supports batching of scene queries via the <em>PxBatchQuery</em> interface. +Using this API may simplify multi-threaded implementations.</p> +<p>The batched query feature has been deprecated in PhysX version 3.4.</p> +<ul class="simple"> +<li><em>PxBatchQuery</em> interface facilitates batching and execution of multiple queries together. PxBatchQuery buffers raycast, overlap and sweep queries until PxBatchQuery::execute() is called.</li> +<li>Use PxScene::createBatchQuery(const PxBatchQueryDesc& desc) to create a PxBatchQuery object.</li> +<li>The hardcoded filtering equation is not used for batched queries. Instead it is replaced with two filter shaders, respectively running before (<em>PxBatchQueryPreFilterShader</em>) and after (<em>PxBatchQueryPostFilterShader</em>) the exact per-shape collision test. See <em>PxBatchQueryDesc::preFilterShader</em> and <em>PxBatchQueryDesc::postFilterShader</em>.</li> +<li>BatchQueryFilterData::filterShaderData will be copied and passed to the filter shader via the constantBlock parameter.</li> +<li>Results are written to user-defined buffers <em>PxBatchQueryMemory</em> in <em>PxBatchQueryDesc</em>, +in the same order queries were queued in a <em>PxBatchQuery</em> object.</li> +<li>The results and hits buffers for the each query type used (raycast, overlap, sweep) are specified separately.</li> +<li>These buffers can be changed before each batch query execute call. +The SDK will produce a warning for batched queries with NULL results or hits buffers for the corresponding query type +(raycast, overlap or sweep).</li> +</ul> +</div> +<div class="section" id="volume-caching"> +<h2>Volume Caching<a class="headerlink" href="#volume-caching" title="Permalink to this headline">¶</a></h2> +<p><em>PxVolumeCache</em> provides a mechanism for accelerating scene queries. This class implements caching for objects within a specified volume and provides an API similar to PxScene for executing raycasts, overlaps, and sweeps. PxVolumeCache can provide a performance boost when objects within the same localized region of space are queried multiple times, either within the same simulation frame or on a later frame.</p> +<p>The volume cache feature has been deprecated in PhysX version 3.4.</p> +<p>Some expected use cases for PxVolumeCache are:</p> +<ul class="simple"> +<li>A particle system with many raycasts performed for each particle from a spatially localized cloud.</li> +<li>Multiple short range character controller raycasts within the same area around the character.</li> +<li>Caching query results across multiple frames, the cache can be filled using a larger volume on previous frame +(possibly extruded in the anticipated direction of movement) and then queried with a smaller volume.</li> +</ul> +<p>The cache has a maximum capacity, specified separately for dynamic and static objects, in <em>PxScene::createVolumeCache()</em>.</p> +<p>For purposes of multithreaded access, any operation on the cache counts as a read call on the scene.</p> +<div class="section" id="filling-the-cache"> +<h3>Filling the Cache<a class="headerlink" href="#filling-the-cache" title="Permalink to this headline">¶</a></h3> +<p>To fill the cache, call <em>PxVolumeCache::fill()</em>. This will query the scene for objects overlapping with the volume defined by the geometry and transform and store the results in an internal buffer up to the maximum sizes for static and dynamic objects. Only PxBoxGeometry, PxSphereGeometry and PxCapsuleGeometry are supported for cacheVolume. The call will always refill both the static and dynamic internal caches, even if the new volume lies entirely within the previous cached volume. It returns a result of type <em>PxVolumeCache::FillStatus</em>.</p> +<p>Subsequent queries against the cache (raycasts, overlaps, sweeps, forEach) will refill the cache automatically using the same volume if the scene query subsystem has been updated since the last fill. The update status is tracked independently for statics and dynamics, so a query might only refill the cache for dynamics while reusing valid cached results for statics. If any attempt to fill or refill fails, the cache is invalid, and any subsequent query will attempt to fill it.</p> +</div> +<div class="section" id="querying-the-cache"> +<h3>Querying the Cache<a class="headerlink" href="#querying-the-cache" title="Permalink to this headline">¶</a></h3> +<p>PxVolumeCache provides an API for raycasts, sweeps and overlaps that is similar to the scene query API. The main difference in signatures is that <a class="reference internal" href="#single-object-caching"><em>Single Object Caching</em></a> is not supported for PxVolumeCache queries. Query results are reported via the <em>PxVolumeCache::Iterator::shapes()</em> callback, and the query may invoke the callback multiple times to deliver multiple batches of results.</p> +<ul class="simple"> +<li>Raycasts, overlaps and sweeps against a valid cache will return only results which overlap the cache volume, but is guaranteed to return all such volumes.</li> +<li>Raycasts, overlaps and sweeps against an invalid cache will fall back to scene queries. In this case results may be returned which do not overlap the cache volume.</li> +</ul> +<p>Since the cache refills automatically on any query where the scene has changed, these two conditions guarantee that a query against the cache that lies entirely within the cache volume will always return exactly the same shapes as querying the scene. If the query does not lie entirely within the cache volume (and the cache is valid) only those shapes which overlap the cache volume will be returned. If a query is issued against a cache on which fill() has never been called, an error is reported.</p> +<p>The cache also provides a low-level <em>forEach()</em> mechanism that iterates over the cached objects. If <em>forEach()</em> is executed on a cache for which <em>fill()</em> has never been called, it will return without reporting an error. If the cache is invalid, forEach() will retrieve the shapes that overlap the cached volume directly from the scene. This process involves the allocation of a temporary buffer, and if the allocation fails, <em>forEach()</em> will emit an error message and return.</p> +<p>This code snippet shows how to use PxVolumeCache:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">poi</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// point of interest</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> +<span class="n">PxRaycastBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Raycast results</span> +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">maxStatics</span> <span class="o">=</span> <span class="mi">32</span><span class="p">,</span> <span class="n">maxDynamics</span> <span class="o">=</span> <span class="mi">8</span><span class="p">;</span> + +<span class="c1">// persistent cache, valid until invalidated by object movement,</span> +<span class="c1">// insertion or deletion</span> +<span class="n">PxVolumeCache</span><span class="o">*</span> <span class="n">cache</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">createVolumeCache</span><span class="p">(</span><span class="n">maxStatics</span><span class="p">,</span> <span class="n">maxDynamics</span><span class="p">);</span> +<span class="n">cache</span><span class="o">-></span><span class="n">setMaxNbStaticShapes</span><span class="p">(</span><span class="mi">64</span><span class="p">);</span> <span class="n">cache</span><span class="o">-></span><span class="n">setMaxNbDynamicShapes</span><span class="p">(</span><span class="mi">16</span><span class="p">);</span> + +<span class="c1">// fill the cache using a box geometry centered around the point of interest</span> +<span class="n">cache</span><span class="o">-></span><span class="n">fill</span><span class="p">(</span><span class="n">PxBoxGeometry</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">)),</span> <span class="n">PxTransform</span><span class="p">(</span><span class="n">position</span><span class="p">));</span> + +<span class="p">...</span> + +<span class="c1">// Perform multiple raycast queries using the cache</span> +<span class="n">PxRaycastBuffer</span> <span class="n">hit</span><span class="p">;</span> +<span class="k">const</span> <span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">cache</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">);</span> + +<span class="c1">// low level iterator for stored actor/shape pairs</span> +<span class="k">struct</span> <span class="n">UserIterator</span> <span class="o">:</span> <span class="n">PxVolumeCache</span><span class="o">::</span><span class="n">Iterator</span> +<span class="p">{</span> + <span class="n">UserData</span> <span class="n">userData</span><span class="p">;</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">shapes</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">count</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxActorShape</span><span class="o">*</span> <span class="n">actorShapePairs</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">count</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">doSomething</span><span class="p">(</span><span class="n">actorShapePairs</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">actor</span><span class="p">,</span> <span class="n">actorShapePairs</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">shape</span><span class="p">,</span> <span class="n">userData</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> <span class="n">iter</span><span class="p">;</span> + +<span class="c1">// invoke UserIterator::shapes() callback for all actor/shape pairs in the cache</span> +<span class="n">cache</span><span class="o">-></span><span class="n">forEach</span><span class="p">(</span><span class="n">iter</span><span class="p">);</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="single-object-caching"> +<span id="id2"></span><h2>Single Object Caching<a class="headerlink" href="#single-object-caching" title="Permalink to this headline">¶</a></h2> +<p>Another special case mechanism for accelerating scene queries is single-object caching, using <em>PxQueryCache</em>.</p> +<ul class="simple"> +<li>This cache can provide additional speedups and memory savings for <em>raycast</em> and <em>sweep</em> queries in any operation mode.</li> +<li>The cache object defines which shape should be tested first. For queries with high temporal +coherence, this can provide significant performance gains. A good strategy to capture that coherence is simply to fill the cache +object of a given query with the eBLOCK result (last blocking shape) from the previous frame.</li> +<li>Note that it is likely incorrect to use a past touching hit (recorded with eTOUCH flag) for caching since it will be interpreted +as blocking and override any filtering.</li> +</ul> +<p>For example there is a good chance that an AI visibility query will return the same line-of-sight blocking shape for several frames. +Using a <em>raycast</em> query with a properly filled <em>PxQueryCache</em> object will allow PhysX to test a single shape - before traversing +the internal spatial partitioning structures, and in case of a "cache hit" the traversal can be bypassed entirely. For instance:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> +<span class="n">PxVec3</span> <span class="n">origin</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Ray origin</span> +<span class="n">PxVec3</span> <span class="n">unitDir</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Normalized ray direction</span> +<span class="n">PxReal</span> <span class="n">maxDistance</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// [in] Raycast max distance</span> +<span class="n">PxRaycastBuffer</span> <span class="n">hit</span><span class="p">;</span> <span class="c1">// [out] Raycast results</span> + +<span class="c1">// Per-raycast persistent cache, valid from one frame to the next</span> +<span class="k">static</span> <span class="n">PxQueryCache</span> <span class="n">persistentCache</span><span class="p">;</span> + +<span class="c1">// Define cache for current frame:</span> +<span class="c1">// - if there was a hit in the previous frame, use the cache.</span> +<span class="c1">// - otherwise do not (PhysX requires given cache has a valid shape pointer)</span> +<span class="k">const</span> <span class="n">PxQueryCache</span><span class="o">*</span> <span class="n">cache</span> <span class="o">=</span> <span class="n">persistentCache</span><span class="p">.</span><span class="n">shape</span> <span class="o">?</span> <span class="o">&</span><span class="n">persistentCache</span> <span class="o">:</span> <span class="nb">NULL</span><span class="p">;</span> + +<span class="c1">// Perform a raycast query using the cache</span> +<span class="k">const</span> <span class="kt">bool</span> <span class="n">status</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">raycast</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">unitDir</span><span class="p">,</span> <span class="n">maxDistance</span><span class="p">,</span> <span class="n">hit</span><span class="p">,</span> + <span class="n">PxHitFlags</span><span class="p">(</span><span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">),</span> + <span class="n">PxQueryFilterData</span><span class="p">(),</span> <span class="nb">NULL</span><span class="p">,</span> <span class="n">cache</span><span class="p">);</span> +<span class="k">if</span><span class="p">(</span><span class="n">status</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">// We hit a shape. Cache it for next frame.</span> + <span class="n">persistentCache</span><span class="p">.</span><span class="n">shape</span> <span class="o">=</span> <span class="n">hit</span><span class="p">.</span><span class="n">block</span><span class="p">.</span><span class="n">shape</span><span class="p">;</span> + <span class="n">persistentCache</span><span class="p">.</span><span class="n">faceIndex</span> <span class="o">=</span> <span class="n">hit</span><span class="p">.</span><span class="n">block</span><span class="p">.</span><span class="n">faceIndex</span><span class="p">;</span> +<span class="p">}</span> +<span class="k">else</span> +<span class="p">{</span> + <span class="c1">// We did not hit anything. Reset the cache for next frame.</span> + <span class="n">persistentCache</span> <span class="o">=</span> <span class="n">PxQueryCache</span><span class="p">();</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Caching can also be useful in queries looking for the closest blocking hit or when using the eANY_HIT flag. +In this case, testing the previously closest object first can allow PhysX to shorten the query distance very early, +leading to fewer total narrow phase collision tests and early out from the traversal.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">PhysX does not detect stale pointers, so the application is responsible for cached object validity when shapes are deleted.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Overlaps do not support single hit blocking caches.</p> +</div> +</div> +<div class="section" id="pxpruningstructuretype"> +<span id="id3"></span><h2>PxPruningStructureType<a class="headerlink" href="#pxpruningstructuretype" title="Permalink to this headline">¶</a></h2> +<p>PhysX SDK offers different pruning structures which are used to accelerate the scene queries. This paragraph describes the differences between them.</p> +<div class="section" id="generalities"> +<h3>Generalities<a class="headerlink" href="#generalities" title="Permalink to this headline">¶</a></h3> +<p>The Scene Query system uses two different acceleration structures, a hierarchical grid and an AABB tree.</p> +<p>The grid builds quickly, in O(n) time, with queries executing in between O(1) and O(N) time depending on how uniformly the objects are +distributed in space, with pathological worst case performance of O(N) when all objects are clustered in the same grid cell.</p> +<p>The tree builds in O(n log(n)) time, but queries with a single result typically run in O(log(n)) time. Queries returning multiple results +will traverse more of the tree, the worst case being a query returning all of the objects in the scene in O(n) time. +The tree is vulnerable to degeneration when the same topology is maintained too long as object positions change, +and in pathological cases query performance may degrade to O(n) time.</p> +<p>Acceleration structures must be continually modified in accordance with objects being added or removed, or object AABB updates +due to changes in position or geometry. To minimize the cost, modifications are deferred for as long as possible. +Thus adding or removing objects or updating AABBs occurs in amortized constant time, with the cost of modifications deferred +until the changes 'commit'. This happens on the next subsequent query or the next fetchResults(). +To force an immediate commit, call the PxScene::flushQueryUpdates() function.</p> +<p>The exact details of the commit process depend on the values of staticStructure and dynamicStructure specified in PxSceneDesc.</p> +<p>To avoid automatic resizing triggered by insertions into internal scene query data structures, reserve the space in advance. +See <em>PxSceneDesc::maxNbStaticShapes</em> and <em>PxSceneDesc::maxNbDynamicShapes</em>.</p> +</div> +<div class="section" id="pxpruningstructuretype-enone"> +<h3>PxPruningStructureType::eNONE<a class="headerlink" href="#pxpruningstructuretype-enone" title="Permalink to this headline">¶</a></h3> +<p>The acceleration structure is similar to a hierarchical grid. Committing changes requires a full rebuild. This is a good choice if you expect +to rarely or never update the objects in this structure.</p> +</div> +<div class="section" id="pxpruningstructuretype-estatic-aabb-tree"> +<h3>PxPruningStructureType::eSTATIC_AABB_TREE<a class="headerlink" href="#pxpruningstructuretype-estatic-aabb-tree" title="Permalink to this headline">¶</a></h3> +<p>The acceleration structure is a tree. Committing changes requires a full rebuild. It is not generally recommended, but can be a good choice +for staticStructure if the static actors in your scene are created on initialization, and not modified thereafter. +If you frequently add or remove static geometry, the default eDYNAMIC_AABB_TREE setting is usually a better choice, although it has a higher +memory footprint than that of eSTATIC_AABB_TREE.</p> +</div> +<div class="section" id="pxpruningstructuretype-edynamic-aabb-tree"> +<h3>PxPruningStructureType::eDYNAMIC_AABB_TREE<a class="headerlink" href="#pxpruningstructuretype-edynamic-aabb-tree" title="Permalink to this headline">¶</a></h3> +<p>In this case, both the tree and the grid are used, and each query searches both the tree and the grid.</p> +<p>The tree is initially built by the first commit. Once a tree is built, committing changes proceeds as follows:: +* the tree is refitted in accordance with updates and removals of object it contains. +* added objects are inserted into the grid. Such additions, or removals of objects currently in the grid, or changes to AABBs +of objects in the grid, cause it to be rebuilt.</p> +<p>In addition, a new tree is incrementally built during fetchResults(), over a number of frames controlled by PxScene's +dynamicTreeRebuildRateHint attribute. When the build starts, it includes all of the objects in the current tree and grid. +When it finishes, some frames later, the new tree is refitted in accordance with any AABB changes or removals since the build started, +and then replaces the current tree. Any objects that were added since the start of the build remain in the grid.</p> +<p>To force a full immediate rebuild, call PxScene::forceDynamicTreeRebuild(). This can be useful in cases such as the following:</p> +<ul class="simple"> +<li>a slow rebuilt rate is typically desirable, but occasionally a large number of object additions creates high occupancy in the grid, +especially if the additions are localized so as to put pressure on just a few of the grid cells.</li> +<li>you are moving many objects across large distances, since refitting may significantly degrade the quality of the current tree</li> +</ul> +</div> +</div> +<div class="section" id="pxpruningstructure"> +<h2>PxPruningStructure<a class="headerlink" href="#pxpruningstructure" title="Permalink to this headline">¶</a></h2> +<p>Provides access to precomputed pruning structure used to accelerate scene queries against newly added actors.</p> +<p>A pruning structure can be provided to PxScene::addActors. The actors scene query shapes will then be directly merged into the scenes AABB tree, without the need of an AABB tree recompute:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Create pruning structure from given actors.</span> +<span class="n">PxPruningStructure</span><span class="o">*</span> <span class="n">ps</span> <span class="o">=</span> <span class="n">PxPhysics</span><span class="o">::</span><span class="n">createPruningStructure</span><span class="p">(</span><span class="o">&</span><span class="n">actors</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="p">(</span><span class="n">PxU32</span><span class="p">)</span><span class="n">actors</span><span class="p">.</span><span class="n">size</span><span class="p">());</span> +<span class="c1">// Add actors into a scene together with the precomputed pruning structure.</span> +<span class="n">PxScene</span><span class="o">::</span><span class="n">addActors</span><span class="p">(</span><span class="o">*</span><span class="n">ps</span><span class="p">);</span> +<span class="n">ps</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>A PxPruningStructure object can be serialized into a collection together with its actors.</p> +<p>For usage of PxPruningStructure please refer to the snippet SnippetPrunerSerialization.</p> +<p>A typical use case for PxPruningStructure is a large world scenario where blocks of closely positioned actors get streamed in.</p> +<div class="section" id="merge-process"> +<h3>Merge process<a class="headerlink" href="#merge-process" title="Permalink to this headline">¶</a></h3> +<p>The merge process into the scene query acceleration structure differs based on <em>PxPruningStructureType</em>: +* eSTATIC_AABB_TREE - the pruning structure is merged directly into scene's AABBtree. This might unbalance the tree and it is recommended to recompute the static tree at some point. +* eDYNAMIC_AABB_TREE - the pruning structure is merged into a temporary pruning structures until the scene's new optimized AABB tree is computed.</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Scene Queries</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#basic-queries">Basic queries</a><ul> +<li><a class="reference internal" href="#raycasts">Raycasts</a></li> +<li><a class="reference internal" href="#sweeps">Sweeps</a></li> +<li><a class="reference internal" href="#overlaps">Overlaps</a></li> +</ul> +</li> +<li><a class="reference internal" href="#touching-and-blocking-hits">Touching and blocking hits</a></li> +<li><a class="reference internal" href="#query-modes">Query modes</a><ul> +<li><a class="reference internal" href="#closest-hit">Closest hit</a></li> +<li><a class="reference internal" href="#any-hit">Any hit</a></li> +<li><a class="reference internal" href="#multiple-hits">Multiple hits</a></li> +<li><a class="reference internal" href="#multiple-hits-with-blocking-hit">Multiple hits with blocking hit</a></li> +</ul> +</li> +<li><a class="reference internal" href="#filtering">Filtering</a><ul> +<li><a class="reference internal" href="#pxqueryflag-estatic-pxqueryflag-edynamic">PxQueryFlag::eSTATIC, PxQueryFlag::eDYNAMIC</a></li> +<li><a class="reference internal" href="#pxqueryflag-eprefilter-pxqueryflag-epostfilter">PxQueryFlag::ePREFILTER, PxQueryFlag::ePOSTFILTER</a></li> +<li><a class="reference internal" href="#pxqueryflag-eany-hit">PxQueryFlag::eANY_HIT</a></li> +<li><a class="reference internal" href="#pxqueryflag-eno-block">PxQueryFlag::eNO_BLOCK</a></li> +<li><a class="reference internal" href="#pxfilterdata-fixed-function-filtering">PxFilterData fixed function filtering</a></li> +</ul> +</li> +<li><a class="reference internal" href="#user-defined-hit-callbacks-for-unbounded-results">User defined hit callbacks for unbounded results</a></li> +<li><a class="reference internal" href="#batched-queries">Batched queries</a></li> +<li><a class="reference internal" href="#volume-caching">Volume Caching</a><ul> +<li><a class="reference internal" href="#filling-the-cache">Filling the Cache</a></li> +<li><a class="reference internal" href="#querying-the-cache">Querying the Cache</a></li> +</ul> +</li> +<li><a class="reference internal" href="#single-object-caching">Single Object Caching</a></li> +<li><a class="reference internal" href="#pxpruningstructuretype">PxPruningStructureType</a><ul> +<li><a class="reference internal" href="#generalities">Generalities</a></li> +<li><a class="reference internal" href="#pxpruningstructuretype-enone">PxPruningStructureType::eNONE</a></li> +<li><a class="reference internal" href="#pxpruningstructuretype-estatic-aabb-tree">PxPruningStructureType::eSTATIC_AABB_TREE</a></li> +<li><a class="reference internal" href="#pxpruningstructuretype-edynamic-aabb-tree">PxPruningStructureType::eDYNAMIC_AABB_TREE</a></li> +</ul> +</li> +<li><a class="reference internal" href="#pxpruningstructure">PxPruningStructure</a><ul> +<li><a class="reference internal" href="#merge-process">Merge process</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="SpatialQueries.html" + title="previous chapter">Spatial Queries</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Vehicles.html" + title="next chapter">Vehicles</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" /> + <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="Vehicles.html" title="Vehicles" + >next</a></li> + <li class="right" > + <a href="SpatialQueries.html" title="Spatial Queries" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Serialization.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Serialization.html new file mode 100644 index 00000000..e6b3d052 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Serialization.html @@ -0,0 +1,927 @@ +<!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>Serialization — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Extending Serialization" href="ExtendingSerialization.html" /> + <link rel="prev" title="Simulation Statistics" href="Statistics.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="ExtendingSerialization.html" title="Extending Serialization" + accesskey="N">next</a></li> + <li class="right" > + <a href="Statistics.html" title="Simulation Statistics" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="serialization"> +<span id="id1"></span><h1>Serialization<a class="headerlink" href="#serialization" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>PhysX 3 features two approaches to serialization:</p> +<ul class="simple"> +<li>API-level serialization to RepX (an XML format)</li> +<li>Binary serialization</li> +</ul> +<p>API-level serialization uses a human readable XML format - RepX - that directly corresponds to the PhysX API. It is therefore suitable for manual inspection and modification for debugging purposes. It offers platform independence and further supports loading data that was serialized with a previous PhysX SDK version. API-level serialization is not expected to be used in performance critical situations.</p> +<p>The binary serialization approach on the other hand supports instantiation of PhysX objects directly from memory without copying data. This in-place deserialization method is well suited for performance critical real time situations. However, this approach is also less flexible as the binary format is specific to a given platform and PhysX SDK version. PhysX provides functionality to convert binary serialized data from authoring platforms to run-time platforms to ease the asset management.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last"><em>cooking</em> also generates a binary output stream. The primary purpose of cooking, however, is to translate from a user format to a format suitable for the SDK runtime, and so it is not considered a serialization mechanism. Loading a cooked mesh from a stream involves allocation and endian conversion. As a consequence, it is much less efficient than PhysX' binary serialization mechanism. See <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollisionshapes"><em>Shapes</em></a> for more details about cooking.</p> +</div> +<p>The following documentation will discuss how to use both serialization approaches. It will show how to build collections of PhysX objects and how these collections are serialized and deserialized. Further it will show how dependencies to other PhysX objects or application side objects can be re-established when deserializing.</p> +<p>PhysX also supports extending serialization to custom types, such as specialized joints. This is described in more detail in Section <a class="reference internal" href="ExtendingSerialization.html#extendedserialization"><em>Extending Serialization</em></a>.</p> +</div> +<div class="section" id="first-code"> +<h2>First Code<a class="headerlink" href="#first-code" title="Permalink to this headline">¶</a></h2> +<p>The following code creates and serializes a rigid dynamic using both RepX and binary formats:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Create a material, a shape and a rigid dynamic</span> +<span class="n">PxSphereGeometry</span> <span class="nf">geometry</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +<span class="n">PxMaterial</span><span class="o">*</span> <span class="n">material</span> <span class="o">=</span> <span class="n">PxGetPhysics</span><span class="p">().</span><span class="n">createMaterial</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="n">PxShape</span><span class="o">*</span> <span class="n">shape</span> <span class="o">=</span> <span class="n">PxGetPhysics</span><span class="p">().</span><span class="n">createShape</span><span class="p">(</span><span class="n">geometry</span><span class="p">,</span> <span class="o">*</span><span class="n">material</span><span class="p">);</span> +<span class="n">PxTransform</span> <span class="n">t</span> <span class="o">=</span> <span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">);</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dynamic</span> <span class="o">=</span> <span class="n">PxCreateDynamic</span><span class="p">(</span><span class="n">PxGetPhysics</span><span class="p">(),</span> <span class="n">t</span><span class="p">,</span> <span class="n">geometry</span><span class="p">,</span> <span class="o">*</span><span class="n">material</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">);</span> + +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createSerializationRegistry</span><span class="p">(</span><span class="n">PxGetPhysics</span><span class="p">());</span> + +<span class="c1">// Create a collection and all objects for serialization</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> +<span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">dynamic</span><span class="p">);</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">complete</span><span class="p">(</span><span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> + +<span class="c1">// Serialize either to binary or RepX</span> +<span class="n">PxDefaultFileOutputStream</span> <span class="nf">outStream</span><span class="p">(</span><span class="s">"serialized.dat"</span><span class="p">);</span> + +<span class="c1">// Binary</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> +</pre></div> +</div> +<p>Most operations related to serialization require an instance of <em>PxSerializationRegistry</em>, which provides information on how to serialize PhysX types. In order to serialize a PhysX object, it needs to be added to a <em>PxCollection</em>. If an object has dependencies on other PhysX objects, they need to be serialized as well. <em>PxSerialization::complete</em> adds all the required objects to the collection.</p> +<p>The following code deserializes the rigid dynamic and adds it to a scene for simulation:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createSerializationRegistry</span><span class="p">(</span><span class="n">PxGetPhysics</span><span class="p">());</span> + +<span class="c1">// Binary</span> + <span class="c1">// Open file and get file size</span> + <span class="kt">FILE</span><span class="o">*</span> <span class="n">fp</span> <span class="o">=</span> <span class="n">fopen</span><span class="p">(</span><span class="s">"serialized.dat"</span><span class="p">,</span> <span class="s">"rb"</span><span class="p">);</span> + <span class="n">fseek</span><span class="p">(</span><span class="n">fp</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">SEEK_END</span><span class="p">);</span> + <span class="kt">unsigned</span> <span class="n">fileSize</span> <span class="o">=</span> <span class="n">ftell</span><span class="p">(</span><span class="n">fp</span><span class="p">);</span> + <span class="n">fseek</span><span class="p">(</span><span class="n">fp</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">SEEK_SET</span><span class="p">);</span> + + <span class="c1">// Allocate aligned memory, load data and deserialize</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">memory</span> <span class="o">=</span> <span class="n">malloc</span><span class="p">(</span><span class="n">fileSize</span><span class="o">+</span><span class="n">PX_SERIAL_FILE_ALIGN</span><span class="p">);</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">memory128</span> <span class="o">=</span> <span class="p">(</span><span class="kt">void</span><span class="o">*</span><span class="p">)((</span><span class="kt">size_t</span><span class="p">(</span><span class="n">memory</span><span class="p">)</span> <span class="o">+</span> <span class="n">PX_SERIAL_FILE_ALIGN</span><span class="p">)</span><span class="o">&~</span><span class="p">(</span><span class="n">PX_SERIAL_FILE_ALIGN</span><span class="o">-</span><span class="mi">1</span><span class="p">));</span> + <span class="n">fread</span><span class="p">(</span><span class="n">memory128</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">fileSize</span><span class="p">,</span> <span class="n">fp</span><span class="p">);</span> + <span class="n">fclose</span><span class="p">(</span><span class="n">fp</span><span class="p">);</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">memory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="c1">// Load file and deserialize collection - needs cooking library</span> + <span class="n">PxDefaultFileInputData</span> <span class="nf">inputData</span><span class="p">(</span><span class="s">"serialized.dat"</span><span class="p">);</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">inputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> + <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="n">scene</span><span class="o">-></span><span class="n">addCollection</span><span class="p">(</span><span class="o">*</span><span class="n">collection</span><span class="p">);</span> +</pre></div> +</div> +<p>When deserializing a binary serialized collection, the data first needs to be copied to a memory block that is aligned to 128 bytes. The memory block may not be deallocated before the objects have been released: it needs to persist for the entire lifetime of the objects. This does not apply to RepX deserialization, as the memory for the corresponding PhysX objects is allocated within PhysX. Finally the objects of the resulting collection can be added to the scene with <em>PxScene::addCollection</em>.</p> +</div> +<div class="section" id="in-depth-discussion"> +<h2>In-depth Discussion<a class="headerlink" href="#in-depth-discussion" title="Permalink to this headline">¶</a></h2> +<div class="section" id="collections"> +<h3>Collections<a class="headerlink" href="#collections" title="Permalink to this headline">¶</a></h3> +<p>The serialization system makes use of a class <em>PxCollection</em>, which manages references to objects deriving from <em>PxBase</em>. Each collection represents a set of objects. Collections maintain a mapping between IDs of type <em>PxSerialObjectId</em> and objects in the collection. IDs may be defined by the application. One caveat here is that the IDs must be unique within a collection, but do not have to be unique across different collections. If the latter is required by the application, it is the application's responsibility to ensure it.</p> +<p>Here is an example of how to iterate over a collection, for instance to ensure that the objects intended for serialization have all been added to the collection. When doing so PhysX' dynamic typing mechanism can be used to classify the objects:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">size</span> <span class="o">=</span> <span class="n">collection</span><span class="o">-></span><span class="n">getNbObjects</span><span class="p">();</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">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="n">PxBase</span><span class="o">*</span> <span class="n">object</span> <span class="o">=</span> <span class="n">collection</span><span class="o">-></span><span class="n">getObject</span><span class="p">(</span><span class="n">i</span><span class="p">);</span> + <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">object</span><span class="o">-></span><span class="n">is</span><span class="o"><</span><span class="n">PxActor</span><span class="o">></span><span class="p">())</span> + <span class="k">continue</span><span class="p">;</span> + + <span class="k">switch</span><span class="p">((</span><span class="n">PxConcreteType</span><span class="p">)</span><span class="n">object</span><span class="o">-></span><span class="n">getConcreteType</span><span class="p">())</span> + <span class="p">{</span> + <span class="k">case</span> <span class="n">PxConcreteType</span>:<span class="o">:</span><span class="n">eRIGID_DYNAMIC</span><span class="o">:</span> + <span class="p">...</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">In order to simplify releasing object within a collection, PhysXExtensions contains a function to remove and release all objects from a collection: <em>PxCollectionExt::releaseObjects</em>.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Releasing an object within a collection invalidates the mapping from indices to objects.</p> +</div> +<p>A collection is said to be <em>complete</em> if no contained objects depend on an object outside of the collection. For example, an actor, a shape with a box geometry, and the material of the shape would together form a complete collection. The same collection without the material would be incomplete.</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/Serialization_Complete.png"><img alt="../_images/Serialization_Complete.png" src="../_images/Serialization_Complete.png" /></a> +<p class="caption">Figure 1: Left: Complete Collection, Right: Incomplete Collection</p> +</div> +<p>For a formal definition please refer to <a class="reference internal" href="#complete"><em>Complete</em></a>.</p> +<p>Both complete and incomplete collections can be serialized, but when deserializing an incomplete collection, references to objects which were not serialized will need to be resolved. The following two sections describe how PhysX collections can be serialized and deserialized using the binary format or RepX. The first section shows how to deal with complete collections, and the second section shows how to deal with incomplete collections.</p> +</div> +<div class="section" id="serializing-complete-collections"> +<h3>Serializing Complete Collections<a class="headerlink" href="#serializing-complete-collections" title="Permalink to this headline">¶</a></h3> +<p>This code snippet shows how to prepare a collection of PhysX objects for serialization (e.g. an actor, its shapes, and the materials and meshes they reference.):</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span><span class="p">;</span> <span class="c1">// The physics SDK object</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">dynamic</span> <span class="o">=</span> <span class="n">PxCreateDynamic</span><span class="p">(...);</span> <span class="c1">// Create a rigid dynamic</span> + + <span class="c1">//Create a serialization registry</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createSerializationRegistry</span><span class="p">(</span><span class="o">*</span><span class="n">physics</span><span class="p">);</span> + +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> <span class="c1">// Create a collection</span> +<span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">dynamic</span><span class="p">);</span> <span class="c1">// Add it to the collection</span> + +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">complete</span><span class="p">(</span><span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> <span class="c1">// Adds all objects required to</span> + <span class="c1">// recreate the dynamic after</span> + <span class="c1">// deserialization</span> +</pre></div> +</div> +<p>Instead of using <em>PxSerialization::complete</em> it is possible to manually add the objects required for serialization. All objects the <em>PxRigidDynamic</em> references would need to be added and then all objects referenced by the newly added objects would need to be added as well and so forth. See definitions: <a class="reference internal" href="#requires"><em>Requires</em></a>, <a class="reference internal" href="#complete"><em>Complete</em></a>.</p> +<p>By default <em>PxSerialization::complete</em> follows references from joints to their actors, but not from actors to their joints. The <em>followJoint</em> parameter can be used to change the behavior of <em>PxSerialization::complete</em> to add the joints attached to each actor. This will cause entire actor-joint chains to be added to the collection.</p> +<p>When all the necessary objects have been added to a collection, create an implementation of the PxOutputStream interface, then serialize the collection:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxColletion</span><span class="o">*</span> <span class="n">collection</span><span class="p">;</span> <span class="c1">// Complete collection without orphans</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">outStream</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + +<span class="c1">// Serialize</span> + +<span class="c1">// Binary</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="c1">// Collection and registry can be released if they are no longer required.</span> +<span class="c1">// Note that releasing the collection will not release the contained objects!</span> +<span class="n">collection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Serialization of objects in a scene that is simultaneously being simulated is not supported and leads to undefined behavior.</p> +</div> +<p>The following code shows how to deserialize a collection from a memory block or XML:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxCooking</span><span class="o">*</span> <span class="n">cooking</span><span class="p">;</span> <span class="c1">// Cooking library needed for</span> + <span class="c1">// instantiating objects by RepX</span> + +<span class="c1">// Deserialize</span> + +<span class="c1">// Binary</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">memory128</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// A 128-byte aligned buffer previously</span> + <span class="c1">// loaded from disk by the user</span> + + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">memory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxInputData</span><span class="o">&</span> <span class="n">inputData</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">inputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> + <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> +</pre></div> +</div> +<p>To add all the objects to the scene and release the collection and registry:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> <span class="c1">// The scene object</span> +<span class="n">scene</span><span class="o">-></span><span class="n">addCollection</span><span class="p">(</span><span class="o">*</span><span class="n">collection</span><span class="p">);</span> +<span class="n">collection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>See <a class="reference internal" href="#serializable"><em>Serializable</em></a> for the exact set of conditions a collection must satisfy in order to be serialized. These conditions can be checked with <em>PxSerialization::isSerializable(...)</em>.</p> +</div> +<div class="section" id="serializing-incomplete-collections"> +<span id="serializingpartialobjectgraphs"></span><h3>Serializing Incomplete Collections<a class="headerlink" href="#serializing-incomplete-collections" title="Permalink to this headline">¶</a></h3> +<p>Another common use case is where a collection of actors and joints - say, a rag doll - will be deserialized multiple times, with each instance sharing the same materials and meshes. To achieve this, serialize two collections:</p> +<ul class="simple"> +<li>a collection A of the materials and meshes that will be deserialized just once</li> +<li>a collection B of actors and joints which will be copied and deserialized multiple times</li> +</ul> +<p>Collection B is <em>incomplete</em>, since it contains references to objects in A. When serializing B, the serialized format will remember each reference to an object in A using that object's ID (if it doesn't have an ID, then serialization will fail.) As long as an object of the right type with a matching ID is supplied when deserializing collection B, the reference can be resolved. Although collection B is incomplete, it is also said to be <em>complete relative to</em> collection A. For a formal definition of complete please refer to <a class="reference internal" href="#complete"><em>Complete</em></a>.</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/Serialization_Dependency.png"><img alt="../_images/Serialization_Dependency.png" src="../_images/Serialization_Dependency.png" /></a> +<p class="caption">Figure 2: Left: Collection <em>A</em> with Sharable Objects, Right: Collection <em>B</em> depending on <em>A</em></p> +</div> +<p>Concretely, to serialize and deserialize an incomplete collection:</p> +<ul class="simple"> +<li>At serialization time, provide IDs for all objects in collection A that are referenced by objects in collection B.</li> +<li>When deserializing, provide a collection with matching IDs for all the objects in A that were referenced by objects in B.</li> +</ul> +<p>Here are examples of how the application can provide identities (<em>PxSerialObjectId</em>) to express requirements of one collection to another. This can be done explicitly when adding the object with:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span><span class="p">;</span> +<span class="n">PxTriangleMesh</span><span class="o">*</span> <span class="n">triMesh</span><span class="p">;</span> +<span class="n">PxSerialObjectId</span> <span class="n">triMeshId</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="c1">// PX_SERIAL_OBJECT_ID_INVALID</span> + <span class="c1">// is a reserved value</span> + +<span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">triMesh</span><span class="p">,</span> <span class="n">triMeshId</span><span class="p">);</span> +</pre></div> +</div> +<p>Or set the ID after adding the object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">triMesh</span><span class="p">);</span> +<span class="n">collection</span><span class="o">-></span><span class="n">addId</span><span class="p">(</span><span class="o">*</span><span class="n">triMesh</span><span class="p">,</span> <span class="n">triMeshId</span><span class="p">);</span> +</pre></div> +</div> +<p>There is a helper function to generate IDs for all objects in a collection that do not have IDs yet:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSerialObjectId</span> <span class="n">baseId</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="c1">// PX_SERIAL_OBJECT_ID_INVALID is</span> + <span class="c1">// a reserved value</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">createSerialObjectIds</span><span class="p">(</span><span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="n">baseId</span><span class="p">);</span> <span class="c1">// Assigns incremental ID values</span> + <span class="c1">// to the collection objects</span> +</pre></div> +</div> +<p>Already used ID values will be skipped by <em>createSerialObjectIds</em>, as well as objects that already have IDs.</p> +<p>After providing correct IDs, all required objects have been added to the collection to be serialized, but without adding the objects that are intended to be referenced. The <em>complete</em> function in <em>PxSerialization</em> supports completing a collection relative to another collection:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> + +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collectionB</span><span class="p">;</span> <span class="c1">// Collection to be completed</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collectionA</span><span class="p">;</span> <span class="c1">// The collection, collectionB</span> + <span class="c1">// will depend on</span> + +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">complete</span><span class="p">(</span><span class="o">*</span><span class="n">collectionB</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="n">collectionA</span><span class="p">);</span> <span class="c1">// Completes collectionB, but</span> + <span class="c1">// ignores objects in collectionA</span> + <span class="c1">// (and also their requirements)</span> +</pre></div> +</div> +<p>Serialization example:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxConvexMesh</span><span class="o">**</span> <span class="n">convexes</span><span class="p">;</span> <span class="c1">// An array of mNbConvexes convexes</span> +<span class="n">PxRigidDynamic</span><span class="o">**</span> <span class="n">actors</span><span class="p">;</span> <span class="c1">// An array of mNbConvexes actors referencing the convexes</span> + +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">convexStream</span><span class="p">;</span> <span class="c1">// Output stream for the convex collection</span> +<span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">actorStream</span><span class="p">;</span> <span class="c1">// Output stream for the actor collection</span> + +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">convexCollection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">actorCollection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> + +<span class="c1">// Add convexes to collection</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">mNbConvexes</span><span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">convexCollection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">convexes</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + +<span class="c1">// Create IDs for the convexes, starting with 1</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">createSerialObjectIds</span><span class="p">(</span><span class="o">*</span><span class="n">convexCollection</span><span class="p">,</span> <span class="n">PxSerialObjectId</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span> + +<span class="c1">// Serialize the convexes along with their IDs</span> + +<span class="c1">// Binary</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">convexStream</span><span class="p">,</span> <span class="o">*</span><span class="n">convexCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">convexStream</span><span class="p">,</span> <span class="o">*</span><span class="n">convexCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="c1">// Add actors to other collection</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">mNbActors</span><span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">actorCollection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">actors</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + +<span class="c1">// Add all required objects except the convexes</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">complete</span><span class="p">(</span><span class="o">*</span><span class="n">actorCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="n">convexCollection</span><span class="p">);</span> + +<span class="c1">// Serialize the actors with references to convexCollection</span> + +<span class="c1">// Binary</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">actorStream</span><span class="p">,</span> <span class="o">*</span><span class="n">actorCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> + <span class="n">convexCollection</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">actorStream</span><span class="p">,</span> <span class="o">*</span><span class="n">actorCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> + <span class="n">convexCollection</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="c1">// Release collections and registry</span> +<span class="n">convexCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">actorCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>Deserialization example:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span><span class="p">;</span> <span class="c1">// The physics SDK object</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxCooking</span><span class="o">*</span> <span class="n">cooking</span><span class="p">;</span> <span class="c1">// Cooking lib needed for instantiating objects (RepX)</span> +<span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> <span class="c1">// The scene into which the objects will be inserted</span> + +<span class="c1">// Deserialize convexes along with their IDs (no external dependencies)</span> + +<span class="c1">// Binary</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">convexMemory128</span><span class="p">;</span> <span class="c1">// Aligned memory containing serialized convexes</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">convexCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">convexMemory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxInputData</span><span class="o">&</span> <span class="n">convexInputData</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">convexCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">convexInputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="c1">// Deserialize actors referencing the convexCollection</span> + +<span class="c1">// Binary</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">actorMemory128</span><span class="p">;</span> <span class="c1">// Aligned memory containing serialized actors</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">actorCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">actorMemory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="n">convexCollection</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxInputData</span><span class="o">&</span> <span class="n">actorInputData</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">actorCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">actorInputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> + <span class="n">convexCollection</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="c1">// Release convex collection</span> +<span class="n">convexCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> + +<span class="c1">// Add actors to scene and release collection and registry</span> +<span class="n">scene</span><span class="o">-></span><span class="n">addCollection</span><span class="p">(</span><span class="o">*</span><span class="n">actorCollection</span><span class="p">);</span> +<span class="n">actorCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>The next example shows how to deal with situations where the serialized objects require objects that are not serialized and deserialized but created by other means:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxMaterial</span><span class="o">**</span> <span class="n">materials</span><span class="p">;</span> <span class="c1">// Created procedurally by application</span> +<span class="n">PxRigidDynamic</span><span class="o">**</span> <span class="n">actors</span><span class="p">;</span> <span class="c1">// An array of mNbConvexes actors referencing the convexes</span> +<span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">actorStream</span><span class="p">;</span> <span class="c1">// Output stream for the actor collection</span> + +<span class="c1">// Add materials with IDs to collection</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">materialCollection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> + +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">mNbMaterials</span><span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">materialCollection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">materials</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">PxSerialObjectId</span><span class="p">(</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">));</span> + +<span class="c1">// Create actor collection, complete and serialize</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">actorCollection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> + +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">mNbActors</span><span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">actorCollection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">actors</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">complete</span><span class="p">(</span><span class="o">*</span><span class="n">actorCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="n">materialCollection</span><span class="p">);</span> + +<span class="c1">// Binary</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">actorStream</span><span class="p">,</span> <span class="o">*</span><span class="n">actorCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> + <span class="n">materialCollection</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">actorStream</span><span class="p">,</span> <span class="o">*</span><span class="n">actorCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> + <span class="n">materialCollection</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="n">actorCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">materialCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> <span class="c1">// Note that materialCollection was not serialized</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>Deserialization:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> <span class="c1">// The scene into which the objects will be inserted</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxCooking</span><span class="o">*</span> <span class="n">cooking</span><span class="p">;</span> <span class="c1">// Cooking library needed for instantiating objects(RepX)</span> +<span class="n">PxMaterial</span><span class="o">**</span> <span class="n">materials</span><span class="p">;</span> <span class="c1">// Created procedurally by application</span> + +<span class="c1">// recreate material collection with consistent IDs, no deserialization</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">materialCollection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> + +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">mNbMaterials</span><span class="p">;</span><span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="n">materialCollection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">materials</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">PxSerialObjectId</span><span class="p">(</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">));</span> + +<span class="c1">// Deserialize actors with reference material collection</span> + +<span class="c1">// Binary</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">actorMemory128</span><span class="p">;</span> <span class="c1">// aligned memory containing serialized actors</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">actorCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">actorMemory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> + <span class="n">materialCollection</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxInputData</span><span class="o">&</span> <span class="n">actorInputData</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">actorCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">actorInputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> + <span class="n">materialCollection</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="n">materialCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">scene</span><span class="o">-></span><span class="n">addCollection</span><span class="p">(</span><span class="o">*</span><span class="n">actorCollection</span><span class="p">);</span> +<span class="n">actorCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="reference-counting-of-deserialized-objects"> +<span id="deserializereferencecounting"></span><h3>Reference Counting of Deserialized Objects<a class="headerlink" href="#reference-counting-of-deserialized-objects" title="Permalink to this headline">¶</a></h3> +<p>This section assumes the background in <a class="reference internal" href="API.html#basicreferencecounting"><em>Reference Counting</em></a>.</p> +<p>Objects that are created by deserialization are always created with a reference that the application needs to give up by explicitly calling <em>release()</em>. The information whether the application gave up a reference to an object is <strong>not</strong> preserved on serialization.</p> +<p>See <a class="reference internal" href="RigidBodyCollision.html#rigidbodycollisionshapes"><em>Shapes</em></a> for a discussion of the method <em>PxRigidActorExt::createExclusiveShape</em>, which automatically releases the initial reference to the shape, leaving only the actor's reference. Again, the information that this reference has been released is not preserved by serialization.</p> +<p>Example for shapes:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">outStream</span><span class="p">;</span> <span class="c1">// Output stream for the collection</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxRigidActor</span><span class="o">*</span> <span class="n">actor</span><span class="p">;</span> <span class="c1">// Any actor</span> + +<span class="c1">// Creating shapes in different ways implies different rules for releasing</span> + +<span class="c1">// Shape is automatically released when actor gets released</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">shapeA</span> <span class="o">=</span> <span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">actor</span><span class="p">,</span> <span class="p">...);</span> + +<span class="c1">// Shape is either created as "shared" or "exclusive" and needs to be released by</span> +<span class="c1">// the application</span> +<span class="n">PxShape</span><span class="o">*</span> <span class="n">shapeB</span> <span class="o">=</span> <span class="n">PxGetPhysics</span><span class="p">().</span><span class="n">createShape</span><span class="p">(...);</span> +<span class="n">actor</span><span class="o">-></span><span class="n">attachShape</span><span class="p">(</span><span class="o">*</span><span class="n">shapeB</span><span class="p">);</span> + +<span class="c1">// Create collection with actor and shapes and serialize</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">PxCreateCollection</span><span class="p">();</span> +<span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">actor</span><span class="p">);</span> +<span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">shapeA</span><span class="p">);</span> +<span class="n">collection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="o">*</span><span class="n">shapeB</span><span class="p">);</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> +<span class="n">collection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> + +<span class="c1">// Releasing actors and shapes</span> +<span class="n">actor</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> <span class="c1">// Releases actor and shapeA (automatically)</span> +<span class="n">shapeB</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> <span class="c1">// Releases shapeB (necessary since shapeB was created through PxPhysics)</span> + +<span class="c1">// Deserialize collection</span> +<span class="p">...</span> +<span class="kt">void</span><span class="o">*</span> <span class="n">memory128</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Aligned memory for serialized data</span> +<span class="n">collection</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">memory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> + +<span class="c1">// Release actors and release ALL shapes (necessary since shape creation history is</span> +<span class="c1">// not preserved across serialization</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">collection</span><span class="o">-></span><span class="n">getNbObjects</span><span class="p">();</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">switch</span> <span class="p">(</span> <span class="n">collection</span><span class="o">-></span><span class="n">getObject</span><span class="p">(</span><span class="n">i</span><span class="p">).</span><span class="n">getConcreteType</span><span class="p">()</span> <span class="p">)</span> + <span class="p">{</span> + <span class="k">case</span> <span class="n">PxConcreteType</span>:<span class="o">:</span><span class="n">eRIGID_DYNAMIC</span><span class="o">:</span> + <span class="k">case</span> <span class="n">PxConcreteType</span>:<span class="o">:</span><span class="n">eRIGID_STATIC</span><span class="o">:</span> + <span class="k">static_cast</span><span class="o"><</span><span class="n">PxActor</span><span class="o">&></span><span class="p">(</span><span class="n">collection</span><span class="o">-></span><span class="n">getObject</span><span class="p">(</span><span class="n">i</span><span class="p">)).</span><span class="n">release</span><span class="p">();</span> <span class="c1">// Doesn't release</span> + <span class="k">break</span><span class="p">;</span> <span class="c1">// any shapes</span> + <span class="k">case</span> <span class="n">PxConcreteType</span>:<span class="o">:</span><span class="n">eSHAPE</span><span class="o">:</span> + <span class="k">static_cast</span><span class="o"><</span><span class="n">PxShape</span><span class="o">&></span><span class="p">(</span><span class="n">collection</span><span class="o">-></span><span class="n">getObject</span><span class="p">(</span><span class="n">i</span><span class="p">)).</span><span class="n">release</span><span class="p">();</span> <span class="c1">// All shapes need to be</span> + <span class="k">break</span><span class="p">;</span> <span class="c1">// released explicitly</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">There is a PhysXExtensions function to release all objects within a collection: <em>PxCollectionExt::releaseObjects</em>.</p> +</div> +</div> +<div class="section" id="reconnecting-physx-and-game-objects"> +<h3>Reconnecting PhysX and Game-Objects<a class="headerlink" href="#reconnecting-physx-and-game-objects" title="Permalink to this headline">¶</a></h3> +<p>Here is an example of how to fix up references with gameplay objects by querying the IDs of a collection:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span><span class="p">;</span> <span class="c1">// The physics SDK object</span> +<span class="n">PxCooking</span><span class="o">*</span> <span class="n">cooking</span><span class="p">;</span> <span class="c1">// Cooking library needed for instantiating objects(RepX)</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> + +<span class="c1">// Deserialize objects along with IDs</span> + +<span class="c1">// Binary</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">memory128</span><span class="p">;</span> <span class="c1">// Aligned memory containing serialized objects</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">memory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxInputData</span><span class="o">&</span> <span class="n">inputData</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">actorInputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">,</span> + <span class="n">materialCollection</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="c1">// Receive a list of all deserialized IDs</span> +<span class="cp">#define MAX_IDS 100</span> +<span class="n">PxSerialObjectId</span> <span class="n">idBuffer</span><span class="p">[</span><span class="n">MAX_IDS</span><span class="p">];</span> +<span class="n">PxU32</span> <span class="n">numIds</span> <span class="o">=</span> <span class="n">collection</span><span class="o">-></span><span class="n">getIds</span><span class="p">(</span><span class="n">idBuffer</span><span class="p">,</span> <span class="n">MAX_IDS</span><span class="p">);</span> + +<span class="c1">// iterate over the list to patch up gameplay objects</span> +<span class="k">for</span> <span class="p">(</span><span class="n">PxU32</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">numIds</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">PxActor</span><span class="o">*</span> <span class="n">actor</span> <span class="o">=</span> <span class="n">collection</span><span class="o">-></span><span class="n">find</span><span class="p">(</span><span class="n">idBuffer</span><span class="p">[</span><span class="n">i</span><span class="p">])</span><span class="o">-></span><span class="n">is</span><span class="o"><</span><span class="n">PxActor</span><span class="o">></span><span class="p">();</span> + <span class="k">if</span> <span class="p">(</span><span class="n">actor</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// this assumes that findGamePlayObjectFromId is able to locate</span> + <span class="c1">// the corresponding game play object from a PxSerialObjectId</span> + <span class="n">actor</span><span class="o">-></span><span class="n">userData</span> <span class="o">=</span> <span class="n">findGamePlayObjectFromId</span><span class="p">(</span><span class="n">idBuffer</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Alternatively <em>PxCollection::getObjects(...)</em> and <em>PxCollection::getId(PxBase& object)</em> can be used to achieve the same.</p> +</div> +<div class="section" id="serializing-everything"> +<h3>Serializing Everything<a class="headerlink" href="#serializing-everything" title="Permalink to this headline">¶</a></h3> +<p>PhysX provides two utility functions for serializing the entirety of the PhysX runtime: <em>PxCollectionExt::createCollection(PxPhysics& sdk)</em> and <em>PxCollectionExt::createCollection(PxScene& scene)</em>:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span><span class="p">;</span> <span class="c1">// The physics SDK object</span> +<span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> <span class="c1">// The physics scene</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">outStream</span><span class="p">;</span> <span class="c1">// The user stream doing the actual write to disk</span> + +<span class="c1">// 1) Create a collection from the set of all objects in the physics SDK that are shareable across</span> +<span class="c1">// multiple scenes.</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">everythingCollection</span> <span class="o">=</span> <span class="n">PxCollectionExt</span><span class="o">::</span><span class="n">createCollection</span><span class="p">(</span><span class="o">*</span><span class="n">physics</span><span class="p">);</span> + +<span class="c1">// 2) Create a collection from all objects in the scene and add it</span> +<span class="c1">// to everythingCollection.</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collectionScene</span> <span class="o">=</span> <span class="n">PxCollectionExt</span><span class="o">::</span><span class="n">createCollection</span><span class="p">(</span><span class="o">*</span><span class="n">scene</span><span class="p">);</span> +<span class="n">everythingCollection</span><span class="o">-></span><span class="n">add</span><span class="p">(</span><span class="n">collectionScene</span><span class="p">);</span> +<span class="n">collectionScene</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> + +<span class="c1">// 3) Complete collection</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">complete</span><span class="p">(</span><span class="o">*</span><span class="n">everythingCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> + +<span class="c1">// 4) serialize collection and release it</span> + +<span class="c1">// Binary</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToBinary</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">everythingCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">everythingCollection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="n">everythingCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>Deserialization is as previously:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxScene</span><span class="o">*</span> <span class="n">scene</span><span class="p">;</span> <span class="c1">// The physics scene</span> +<span class="n">PxCooking</span><span class="o">*</span> <span class="n">cooking</span><span class="p">;</span> <span class="c1">// Cooking library needed for instantiating objects by RepX</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> + +<span class="c1">// Binary</span> + <span class="kt">void</span><span class="o">*</span> <span class="n">memory128</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// a 128-byte aligned buffer previously loaded from disk</span> + <span class="c1">// by the user</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">everythingCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromBinary</span><span class="p">(</span><span class="n">memory128</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~Binary</span> + +<span class="c1">// RepX</span> + <span class="n">PxInputData</span><span class="o">&</span> <span class="n">inputData</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// Implemented by the application</span> + <span class="n">PxCollection</span><span class="o">*</span> <span class="n">everythingCollection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">inputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +<span class="c1">//~RepX</span> + +<span class="n">scene</span><span class="o">-></span><span class="n">addCollection</span><span class="p">(</span><span class="o">*</span><span class="n">everythingCollection</span><span class="p">);</span> +<span class="n">everythingCollection</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">registry</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="serializability"> +<h3>Serializability<a class="headerlink" href="#serializability" title="Permalink to this headline">¶</a></h3> +<p>This section contains various definitions to describe serializability of a collection. Whether a collection can be successfully serialized and deserialized, optionally given an external references collection, can be queried by calling <em>PxSerialization::isSerializable(...)</em></p> +<div class="section" id="requires"> +<span id="id2"></span><h4>Requires<a class="headerlink" href="#requires" title="Permalink to this headline">¶</a></h4> +<p>An object <strong>A</strong> requires another object <strong>B</strong> if <strong>A</strong> maintains a reference to <strong>B</strong> that needs to be re-established for successfully deserializing <strong>A</strong>. This implies that <strong>B</strong> needs to be deserialized before <strong>A</strong>.</p> +<p>Here is the table of the relationship <strong>requires</strong> of all PhysX objects:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="15%" /> +<col width="85%" /> +</colgroup> +<tbody valign="top"> +<tr class="row-odd"><td><strong>joints</strong></td> +<td>require their <strong>actors</strong> and <strong>constraint</strong></td> +</tr> +<tr class="row-even"><td><strong>rigid actors</strong></td> +<td>require their <strong>shapes</strong></td> +</tr> +<tr class="row-odd"><td><strong>shapes</strong></td> +<td>require their <strong>materials</strong> and <strong>mesh</strong> (triangle mesh, convex mesh or height field), if any</td> +</tr> +<tr class="row-even"><td><strong>articulations</strong></td> +<td>require their <strong>links</strong> and <strong>joints</strong></td> +</tr> +<tr class="row-odd"><td><strong>aggregates</strong></td> +<td>require their <strong>actors</strong></td> +</tr> +<tr class="row-even"><td><strong>cloth actors</strong></td> +<td>require their <strong>cloth fabric</strong></td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="subordinate"> +<span id="id3"></span><h4>Subordinate<a class="headerlink" href="#subordinate" title="Permalink to this headline">¶</a></h4> +<p>Subordinates are objects that cannot be instantiated without being owned by other objects. An articulation link, for example, can only be instantiated as part of its articulation.</p> +<p>The following three types are <strong>subordinates</strong>:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="100%" /> +</colgroup> +<tbody valign="top"> +<tr class="row-odd"><td><strong>articulation links</strong></td> +</tr> +<tr class="row-even"><td><strong>articulation joint</strong></td> +</tr> +<tr class="row-odd"><td><strong>constraints</strong></td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="complete"> +<span id="id4"></span><h4>Complete<a class="headerlink" href="#complete" title="Permalink to this headline">¶</a></h4> +<p>Definition of a complete set:</p> +<p>A set of objects <strong>C</strong> is <strong>complete</strong> if every object <strong>required</strong> by <strong>C</strong> is in <strong>C</strong>.</p> +<p>Definition of a set that is complete relative to another set:</p> +<p>A set of objects <strong>C</strong> is <strong>complete</strong> relative to a set <strong>D</strong> if every object <strong>required</strong> by <strong>C</strong> is in <strong>C</strong> or in <strong>D</strong>. This means that <strong>C</strong> can be deserialized given <strong>D</strong>.</p> +</div> +<div class="section" id="serializable"> +<span id="id5"></span><h4>Serializable<a class="headerlink" href="#serializable" title="Permalink to this headline">¶</a></h4> +<p>Here is the complete set of requirements on a collection <strong>C</strong> with dependencies to <strong>D</strong> such that <strong>C</strong> can be serialized:</p> +<ul class="simple"> +<li><strong>C</strong> is complete relative to <strong>D</strong>. ("no dangling references")</li> +<li>Every object in <strong>D</strong> required by an object in <strong>C</strong> has a valid ID. ("no unnamed references")</li> +<li>Every subordinate object in <strong>C</strong> is required by another object in <strong>C</strong>. ("no orphans")</li> +</ul> +</div> +</div> +<div class="section" id="binary-serialization-specifics"> +<h3>Binary Serialization Specifics<a class="headerlink" href="#binary-serialization-specifics" title="Permalink to this headline">¶</a></h3> +<p>The following sections describe specific properties of the binary serialization system.</p> +<div class="section" id="memory-management"> +<h4>Memory Management<a class="headerlink" href="#memory-management" title="Permalink to this headline">¶</a></h4> +<p>Management of memory blocks containing deserialized objects is left to users. It is the user's responsibility to:</p> +<ul class="simple"> +<li>allocate the memory block. Note that it must be properly aligned, to a <em>PX_SERIAL_FILE_ALIGN</em> (128) bytes boundary.</li> +<li>fill the block with serialized data, typically by loading it from disk.</li> +<li>deallocate the memory block when the objects within have been released by PhysX.</li> +</ul> +<p>Although the user owns the memory block, the PhysX runtime owns any deserialized objects it contains. Concretely, calling release() on an object that was created by deserialization will cause its destructor to run, but will not deallocate its memory. If the block is deallocated before the destructors have run for all the objects it contains, the PhysX runtime will likely crash. For more information about how deserialized objects need to be released see <a class="reference internal" href="#deserializereferencecounting"><em>Reference Counting of Deserialized Objects</em></a>.</p> +</div> +<div class="section" id="versioning"> +<span id="retargeting"></span><h4>Versioning<a class="headerlink" href="#versioning" title="Permalink to this headline">¶</a></h4> +<p>The binary serialized data is typically specific to the version of the SDK it was produced with. However, a SDK version can load the data of older SDK versions if the binary format didn't change. This is usually the case with bugfix releases. The compatible SDK versions are listed in the code documentation of <em>PX_BINARY_SERIAL_VERSION</em> in <em>PxSerialization.h</em>.</p> +</div> +<div class="section" id="retargeting-to-other-platforms"> +<h4>Retargeting to other Platforms<a class="headerlink" href="#retargeting-to-other-platforms" title="Permalink to this headline">¶</a></h4> +<p>Binary serialized data is platform-specific, and when serialized it always targets the platform on which it was created. The binary converter in the extensions library retargets data from one platform to another. Typically assets are serialized on an authoring platform (Windows, Mac OS X and Linux). The serialized data can then be retargeted, for example, to a console or any other runtime platform.</p> +<p>The converter requires meta-data for the source and target platforms, which contains information about the binary layout of objects for that platform. To obtain metadata, use the function provided in the extensions library for each platform:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">dumpBinaryMetaData</span><span class="p">(</span><span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">stream</span><span class="p">,</span> <span class="n">PxSerializationRegistry</span><span class="o">&</span> <span class="n">sr</span><span class="p">);</span> +</pre></div> +</div> +<p>On each target platform, run it once and keep generated data around. Alternatively a set of pre-built binary metadata is included with the PhysX SDK at [path to installed PhysX SDK]/Tools/BinaryMetaData.</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/Serialization_Retargeting.png"><img alt="../_images/Serialization_Retargeting.png" src="../_images/Serialization_Retargeting.png" /></a> +<p class="caption">Figure 3: Schema of Retargeting</p> +</div> +<p>Assuming that the extensions library has been initialized, conversion takes place as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> +<span class="n">PxInputStream</span><span class="o">&</span> <span class="n">srcMetadata</span><span class="p">;</span> <span class="c1">// metadata for the 'from' platform</span> + <span class="c1">// (e.g. PxDefaultFileInputData)</span> +<span class="n">PxInputStream</span><span class="o">&</span> <span class="n">dstMetadata</span><span class="p">;</span> <span class="c1">// metadata for the 'to' platform</span> + +<span class="n">PxInputStream</span><span class="o">&</span> <span class="n">srcAsset</span><span class="p">;</span> <span class="c1">// stream containing source asset</span> +<span class="n">PxU32</span> <span class="n">srcAssetSize</span><span class="p">;</span> <span class="c1">// size of the source asset</span> +<span class="n">PxOutputStream</span><span class="o">&</span> <span class="n">dstAsset</span><span class="p">;</span> <span class="c1">// output stream for retargeted asset</span> + +<span class="n">PxBinaryConverter</span><span class="o">*</span> <span class="n">converter</span> <span class="o">=</span> <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createBinaryConverter</span><span class="p">();</span> +<span class="n">converter</span><span class="o">-></span><span class="n">setMetaData</span><span class="p">(</span><span class="n">srcMetadata</span><span class="p">,</span> <span class="n">dstMetadata</span><span class="p">);</span> +<span class="n">converter</span><span class="o">-></span><span class="n">convert</span><span class="p">(</span><span class="n">srcAsset</span><span class="p">,</span> <span class="n">srcAssetSize</span><span class="p">,</span> <span class="n">dstAsset</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="the-convert-tool"> +<h4>The Convert Tool<a class="headerlink" href="#the-convert-tool" title="Permalink to this headline">¶</a></h4> +<p>The convert tool is at [path to installed PhysX SDK]/Snippets/SnippetConvert. It illustrates how to convert PhysX 3 serialized binary files from +one platform to another. It only compiles and runs on authoring platforms (Windows, MacOs and Linux).</p> +<p>SnippetConvert is a simple command-line tool supporting the following options:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="o">--</span><span class="n">srcMetadata</span><span class="o">=<</span><span class="n">filename</span><span class="o">></span> <span class="n">Defines</span> <span class="n">source</span> <span class="n">metadata</span> <span class="n">file</span> +<span class="o">--</span><span class="n">dstMetadata</span><span class="o">=<</span><span class="n">filename</span><span class="o">></span> <span class="n">Defines</span> <span class="n">target</span> <span class="n">metadata</span> <span class="n">file</span> +<span class="o">--</span><span class="n">srcBinFile</span><span class="o">=<</span><span class="n">filename</span><span class="o">></span> <span class="n">Source</span> <span class="n">binary</span> <span class="n">file</span> <span class="n">to</span> <span class="n">convert</span> +<span class="o">--</span><span class="n">dstBinFile</span><span class="o">=<</span><span class="n">filename</span><span class="o">></span> <span class="n">Outputs</span> <span class="n">target</span> <span class="n">binary</span> <span class="n">file</span> +<span class="o">--</span><span class="n">generateExampleFile</span><span class="o">=<</span><span class="n">filename</span><span class="o">></span> <span class="n">Generates</span> <span class="n">an</span> <span class="n">example</span> <span class="n">file</span> +<span class="o">--</span><span class="n">verbose</span> <span class="n">Enables</span> <span class="n">verbose</span> <span class="n">mode</span> +</pre></div> +</div> +</div> +<div class="section" id="object-names"> +<h4>Object Names<a class="headerlink" href="#object-names" title="Permalink to this headline">¶</a></h4> +<p>Some SDK objects, such as shapes and actors, can be given names using the <em>PxShape::setName()</em> and <em>PxActor::setName()</em> functions. By default these names are not serialized. The 'exportNames' parameter of the <em>PxSerialization::serializeCollectionToBinary()</em> can be set to true in order to serialize the names along with the objects.</p> +</div> +</div> +<div class="section" id="api-level-serialization-repx-specifics"> +<h3>API-level Serialization (RepX) Specifics<a class="headerlink" href="#api-level-serialization-repx-specifics" title="Permalink to this headline">¶</a></h3> +<p>RepX stands for Representation X and is the ASCII-XML serialization format for PhysX 3. As opposed to binary serialization, the RepX XML serialization is not intended to be used in performance critical or memory constrained situations. The following sections describe specifics of the RepX XML serialization system.</p> +<div class="section" id="upgrading-repx-data"> +<h4>Upgrading RepX Data<a class="headerlink" href="#upgrading-repx-data" title="Permalink to this headline">¶</a></h4> +<p>Upgrading RepX data from an older PhysX version to a newer one is easy. It happens implicitly when deserializing old RepX data with a newer PhysX SDK and re-serializing the resulting PxCollection.</p> +<p>Example for upgrading a RepX stream:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span><span class="p">;</span> <span class="c1">// The physics SDK object (e.g.</span> + <span class="c1">// PhxsX 3.3)</span> +<span class="n">PxCooking</span><span class="o">*</span> <span class="n">cooking</span><span class="p">;</span> <span class="c1">// Cooking library needed for</span> + <span class="c1">// instantiating objects</span> +<span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">registry</span><span class="p">;</span> <span class="c1">// Registry for serializable types</span> + +<span class="n">PxDefaultFileInputData</span> <span class="nf">inputData</span><span class="p">(</span><span class="n">pathTo30RepXFile</span><span class="p">);</span> <span class="c1">//load an older 3.x RepX file</span> +<span class="n">PxCollection</span><span class="o">*</span> <span class="n">collection</span> <span class="o">=</span> + <span class="n">PxSerialization</span><span class="o">::</span><span class="n">createCollectionFromXml</span><span class="p">(</span><span class="n">inputData</span><span class="p">,</span> <span class="o">*</span><span class="n">cooking</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> + +<span class="n">PxDefaultFileOutputStream</span> <span class="nf">outStream</span><span class="p">(</span><span class="n">pathToNewRepXFile</span><span class="p">);</span> +<span class="n">PxSerialization</span><span class="o">::</span><span class="n">serializeCollectionToXml</span><span class="p">(</span><span class="n">outStream</span><span class="p">,</span> <span class="o">*</span><span class="n">collection</span><span class="p">,</span> <span class="o">*</span><span class="n">registry</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="id6"> +<h4>Object Names<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4> +<p>As opposed to binary serialization, the object names that can be specified with the <em>PxShape::setName()</em> and <em>PxActor::setName()</em> functions, are always included in the serialized format. On deserialization with <em>PxSerialization::createCollectionFromXml(...)</em> the names can be recovered by setting the <em>PxStringTable</em> parameter.</p> +<p>If <em>PxStringTable</em> parameter is set, the names will live within the memory which is allocated by the string table. The string table must not be released unless it can be guaranteed that the names will not be accessed any more.</p> +</div> +<div class="section" id="caching-cooked-geometry-data"> +<span id="cachingcookedgeometrydata"></span><h4>Caching Cooked Geometry Data<a class="headerlink" href="#caching-cooked-geometry-data" title="Permalink to this headline">¶</a></h4> +<p>In order to facilitate faster instantiation of XML data, it is possible to configure the XML serialization to store the cooked triangle and convex mesh data along with the plain data. The cooked data caching can be enabled by passing a <em>PxCooking</em> instance into <em>PxSerialization::serializeCollectionToXml(...)</em>. The cached cooked data is ignored when its format is incompatible with the current SDK version.</p> +</div> +</div> +</div> +<div class="section" id="common-use-cases"> +<h2>Common Use Cases<a class="headerlink" href="#common-use-cases" title="Permalink to this headline">¶</a></h2> +<p>API-level RepX serialization should be used whenever compatibility and human readability are important. The PhysX plug-ins for the DCC tools 3ds Max and Maya use RepX to export PhysX objects. The resulting RepX files can then be deserialized and loaded into the PhysX runtime. This is useful for rapid prototyping or for generally loading PhysX assets if performance is not of a big concern. For quick loading of assets it is better to convert RepX data into binary serialized data. RepX is also useful for reproducing situations with unwanted behavior without the need to provide the whole application. For this, the application may be connected to the PhysX Visual Debugger (PVD), which records the scene of interest. A representative frame can then be saved in RepX format from within PVD (see <a class="reference internal" href="#pvd"><em>PVD</em></a>).</p> +<p>Binary serialization should be used in performance and memory constrained situations. The main target use-case is streaming in chunks of a large game level that can't be loaded into memory at once. Creating and loading save games is another application that could be optimized by using binary serialization. PhysX objects in binary format can also be sent over the network to enable efficient game state synchronization.</p> +</div> +<div class="section" id="snippet-discussion"> +<h2>Snippet Discussion<a class="headerlink" href="#snippet-discussion" title="Permalink to this headline">¶</a></h2> +<p>The following snippets illustrate common operations such as managing collections, serialization, deserialization and re-targeting of binary data.</p> +<div class="section" id="snippetserialization"> +<h3>SnippetSerialization<a class="headerlink" href="#snippetserialization" title="Permalink to this headline">¶</a></h3> +<p>SnippetSerialization shows binary and XML serialization of a scene with a number of jointed rigid bodies representing a chain. This is done in a way that allows the instantiation of multiple chains while sharing the shape and the material across all chains. The snippet shows how to create and populate collections, specify IDs to enable resolving dependencies, serialize collections, deserialize collections and add actors to the scene for simulation.</p> +<p>The snippet also shows how to allocate a data block aligned to 128 bytes and demonstrates how to copy binary serialized data into it. It further demonstrates that the data blocks containing the binary deserialized collections must be maintained until the corresponding objects are not needed anymore and have been released.</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/Serialization_Snippet.png"><img alt="../_images/Serialization_Snippet.png" src="../_images/Serialization_Snippet.png" /></a> +<p class="caption">Figure 4: SnippetSerialization</p> +</div> +</div> +<div class="section" id="snippetconvert"> +<h3>SnippetConvert<a class="headerlink" href="#snippetconvert" title="Permalink to this headline">¶</a></h3> +<p>SnippetConvert illustrates how binary serialized data can be re-targeted from an authoring platform to a runtime platform such as a console. The snippet is a simple command line tool that can load a binary serialized data file along with meta data files for both source and destination platforms and then output a converted binary data file. See the snippet's source documentation for more details on usage.</p> +</div> +<div class="section" id="snippetloadcollection"> +<h3>SnippetLoadCollection<a class="headerlink" href="#snippetloadcollection" title="Permalink to this headline">¶</a></h3> +<p>SnippetLoadCollection shows how to deserialize serialized collections from either binary or XML format. The snippet is a command line tool that can connect to the PhysX Visual Debugger application and display the content of serialized collection files. See the snippet's source documentation for more details.</p> +</div> +</div> +<div class="section" id="best-practices-troubleshooting"> +<h2>Best practices / Troubleshooting<a class="headerlink" href="#best-practices-troubleshooting" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li>Concurrent simulation and serialization is not supported and leads to undefined behavior.</li> +<li>If releasing PhysX objects leads to crashes or errors it is possible that the application is releasing some objects twice. The following two reasons should be considered: 1.) A potential source of error is to release PhysX objects without updating collections referencing these objects. 2.) Shapes that where created through an actor have their application reference automatically released on creation. If such a shape is serialized and deserialized the creation history will be lost. It might be convenient to use the extension function <em>PxCollectionExt::releaseObjects</em> because it deals with the different cases as required. See <a class="reference internal" href="#deserializereferencecounting"><em>Reference Counting of Deserialized Objects</em></a>.</li> +<li>If accessing binary deserialized PhysX objects, including accesses during simulation, causes crashes it might be due to the premature release of the memory block that holds the deserialized objects.</li> +<li>If binary files are too large and/or too slow to load it might be that shared assets have been serialized multiple times. An example of a shared asset might be a mesh that is referenced by multiple shapes. The solution is to separate shared PhysX objects into a separate collection. See <a class="reference internal" href="#serializingpartialobjectgraphs"><em>Serializing Incomplete Collections</em></a>.</li> +<li>If loading PhysX objects from RepX files is too slow two things should be considered: 1.) Could binary serialization be used instead? Even for debugging it might make sense to convert RepX files into binary serialized data by re-serializing them with the binary approach. 2.) Meshes tend to load very slowly from text files. RepX serialization offers an option to cache cooked mesh data by in-lining binary data into the RepX file. If such a cache is present and valid, the loading can become significantly faster. See <a class="reference internal" href="#cachingcookedgeometrydata"><em>Caching Cooked Geometry Data</em></a>.</li> +</ul> +</div> +<div class="section" id="pvd"> +<span id="id7"></span><h2>PVD<a class="headerlink" href="#pvd" title="Permalink to this headline">¶</a></h2> +<p>The PhysX Remote Debugger provides the functionality to export single frames of PhysX scenes as RepX files. The resulting files can be used to playback a snapshot of the PhysX state. In many cases this is sufficient to isolate an issue. The option can be found in the menu of PVD: +[Menu > File > Export Current Frame To RepX]</p> +<div class="figure align-center"> +<a class="reference internal image-reference" href="../_images/Serialization_PVD.png"><img alt="../_images/Serialization_PVD.png" src="../_images/Serialization_PVD.png" /></a> +<p class="caption">Figure 5: RepX Functionality in PVD</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Serialization</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#first-code">First Code</a></li> +<li><a class="reference internal" href="#in-depth-discussion">In-depth Discussion</a><ul> +<li><a class="reference internal" href="#collections">Collections</a></li> +<li><a class="reference internal" href="#serializing-complete-collections">Serializing Complete Collections</a></li> +<li><a class="reference internal" href="#serializing-incomplete-collections">Serializing Incomplete Collections</a></li> +<li><a class="reference internal" href="#reference-counting-of-deserialized-objects">Reference Counting of Deserialized Objects</a></li> +<li><a class="reference internal" href="#reconnecting-physx-and-game-objects">Reconnecting PhysX and Game-Objects</a></li> +<li><a class="reference internal" href="#serializing-everything">Serializing Everything</a></li> +<li><a class="reference internal" href="#serializability">Serializability</a><ul> +<li><a class="reference internal" href="#requires">Requires</a></li> +<li><a class="reference internal" href="#subordinate">Subordinate</a></li> +<li><a class="reference internal" href="#complete">Complete</a></li> +<li><a class="reference internal" href="#serializable">Serializable</a></li> +</ul> +</li> +<li><a class="reference internal" href="#binary-serialization-specifics">Binary Serialization Specifics</a><ul> +<li><a class="reference internal" href="#memory-management">Memory Management</a></li> +<li><a class="reference internal" href="#versioning">Versioning</a></li> +<li><a class="reference internal" href="#retargeting-to-other-platforms">Retargeting to other Platforms</a></li> +<li><a class="reference internal" href="#the-convert-tool">The Convert Tool</a></li> +<li><a class="reference internal" href="#object-names">Object Names</a></li> +</ul> +</li> +<li><a class="reference internal" href="#api-level-serialization-repx-specifics">API-level Serialization (RepX) Specifics</a><ul> +<li><a class="reference internal" href="#upgrading-repx-data">Upgrading RepX Data</a></li> +<li><a class="reference internal" href="#id6">Object Names</a></li> +<li><a class="reference internal" href="#caching-cooked-geometry-data">Caching Cooked Geometry Data</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#common-use-cases">Common Use Cases</a></li> +<li><a class="reference internal" href="#snippet-discussion">Snippet Discussion</a><ul> +<li><a class="reference internal" href="#snippetserialization">SnippetSerialization</a></li> +<li><a class="reference internal" href="#snippetconvert">SnippetConvert</a></li> +<li><a class="reference internal" href="#snippetloadcollection">SnippetLoadCollection</a></li> +</ul> +</li> +<li><a class="reference internal" href="#best-practices-troubleshooting">Best practices / Troubleshooting</a></li> +<li><a class="reference internal" href="#pvd">PVD</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Statistics.html" + title="previous chapter">Simulation Statistics</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ExtendingSerialization.html" + title="next chapter">Extending Serialization</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" /> + <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="ExtendingSerialization.html" title="Extending Serialization" + >next</a></li> + <li class="right" > + <a href="Statistics.html" title="Simulation Statistics" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Simulation.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Simulation.html new file mode 100644 index 00000000..ab012748 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Simulation.html @@ -0,0 +1,286 @@ +<!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>Simulation — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Advanced Collision Detection" href="AdvancedCollisionDetection.html" /> + <link rel="prev" title="Rigid Body Dynamics" href="RigidBodyDynamics.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="AdvancedCollisionDetection.html" title="Advanced Collision Detection" + accesskey="N">next</a></li> + <li class="right" > + <a href="RigidBodyDynamics.html" title="Rigid Body Dynamics" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="simulation"> +<span id="id1"></span><h1>Simulation<a class="headerlink" href="#simulation" title="Permalink to this headline">¶</a></h1> +<div class="section" id="callback-sequence"> +<span id="callbacks"></span><h2>Callback Sequence<a class="headerlink" href="#callback-sequence" title="Permalink to this headline">¶</a></h2> +<p>The simplest type of simulation callbacks are the events. Using callbacks the application can simply listen for events and react as required, provided the callbacks obey the rule that SDK state changes are forbidden. This restriction may be a bit surprising given that the SDK permits writes to an inactive back-buffer while the simulation is running. Event callbacks, however, are not called from within the simulation thread, but rather from inside fetchResults(). The key point here is that fetchResults() processes the buffered writes, meaning that writing to the SDK from an event callback can be a particularly fragile affair. To avoid this fragility it is necessary to impose the rule that SDK state changes are not permitted from an event callback.</p> +<p>Inside fetchResults(), among other things, the buffers are swapped. More specifically, this means that properties of each object's internal simulation state are copied to the API-visible state. Some event callbacks happen before this swap, and some after. The events that happen before are:</p> +<blockquote> +<div><ul class="simple"> +<li>onTrigger</li> +<li>onContact</li> +<li>onConstraintBreak</li> +</ul> +</div></blockquote> +<p>When these events are received in the callback, the shapes, actors, etc. will still be in the state they were in immediately before the simulation started. This is preferable, because these events were detected early on during the simulation, before objects were integrated (moved) forward. For example, a pair of shapes that get an onContact() to report that they are in contact will still be in contact when the call is made, even though they may have bounced apart again after fetchResults() returns.</p> +<p>On the other hand, these events are sent after the swap:</p> +<blockquote> +<div><ul class="simple"> +<li>onSleep</li> +<li>onWake</li> +</ul> +</div></blockquote> +<p>Sleep information is updated after objects have been integrated, so it makes sense to send these events after the swap.</p> +<p>To 'listen' to any of these events it is necessary to first subclass PxSimulationEventCallback so that the various virtual functions may be implemented as desired. An instance of this subclass can then be registered per scene with either PxScene::setSimulationEventCallback or PxSceneDesc::simulationEventCallback. Following these steps alone will ensure that constraint break events are successfully reported. One further step is required to report sleep and wake events: to avoid the expense of reporting all sleep and wake events, actors identified as worthy of sleep/wake notification require the flag PxActorFlag::eSEND_SLEEP_NOTIFIES to be raised. Finally, to receive onContact and onTrigger events it is necessary to set a flag in the filter shader callback for all pairs of interacting objects for which events are required. More details of the filter shader callback can be found in Section <a class="reference internal" href="RigidBodyCollision.html#collisionfiltering"><em>Collision Filtering</em></a>.</p> +</div> +<div class="section" id="simulation-memory"> +<span id="id2"></span><h2>Simulation memory<a class="headerlink" href="#simulation-memory" title="Permalink to this headline">¶</a></h2> +<p>PhysX relies on the application for all memory allocation. The primary interface is via the PxAllocatorCallback interface required to initialize the SDK:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">PxAllocatorCallback</span> +<span class="p">{</span> +<span class="nl">public:</span> + <span class="k">virtual</span> <span class="o">~</span><span class="n">PxAllocatorCallback</span><span class="p">()</span> <span class="p">{}</span> + <span class="k">virtual</span> <span class="kt">void</span><span class="o">*</span> <span class="n">allocate</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">typeName</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">filename</span><span class="p">,</span> + <span class="kt">int</span> <span class="n">line</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">deallocate</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span> <span class="n">ptr</span><span class="p">)</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>After the self-explanatory function argument describing the size of the allocation, the next three function arguments are an identifier name, which identifies the type of allocation, and the __FILE__ and __LINE__ location inside the SDK code where the allocation was made. More details of these function arguments can be found in the PhysXAPI documentation.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">An important change since 2.x: The SDK now requires that the memory that is returned be 16-byte aligned. On many platforms malloc() returns memory that is 16-byte aligned, but on Windows the system function _aligned_malloc() provides this capability.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">On some platforms PhysX uses system library calls to determine the correct type name, and the system function that returns the type name may call the system memory allocator. If you are instrumenting system memory allocations, you may observe this behavior. To prevent PhysX requesting type names, disable allocation names using the method PxFoundation::setReportAllocationNames().</p> +</div> +<p>Minimizing dynamic allocation is an important aspect of performance tuning. PhysX provides several mechanisms to control and analyze memory usage. These shall be discussed in turn.</p> +<div class="section" id="scene-limits"> +<h3>Scene Limits<a class="headerlink" href="#scene-limits" title="Permalink to this headline">¶</a></h3> +<p>The number of allocations for tracking objects can be minimized by presizing the capacities of scene data structures, using either PxSceneDesc::limits before creating the scene or the function PxScene::setLimits(). It is useful to note that these limits do not represent hard limits, meaning that PhysX will automatically perform further allocations if the number of objects exceeds the scene limits.</p> +</div> +<div class="section" id="k-data-blocks"> +<h3>16K Data Blocks<a class="headerlink" href="#k-data-blocks" title="Permalink to this headline">¶</a></h3> +<p>Much of the memory PhysX uses for simulation is held in a pool of blocks, each 16K in size. The initial number of blocks allocated to the pool can be controlled by setting PxSceneDesc::nbContactDataBlocks, while the maximum number of blocks that can ever be in the pool is governed by PxSceneDesc::maxNbContactDataBlocks. If PhysX internally needs more blocks than nbContactDataBlocks then it will automatically allocate further blocks to the pool until the number of blocks reaches maxNbContactDataBlocks. If PhysX subsequently needs more blocks than the maximum number of blocks then it will simply start dropping contacts and joint constraints. When this happens warnings are passed to the error stream in the PX_CHECKED configuration.</p> +<p>To help tune nbContactDataBlocks and maxNbContactDataBlocks it can be useful to query the number of blocks currently allocated to the pool using the function PxScene::getNbContactDataBlocksUsed(). It can also be useful to query the maximum number of blocks that can ever be allocated to the pool with PxScene::getMaxNbContactDataBlocksUsed.</p> +<p>Unused blocks can be reclaimed using PxScene::flushSimulation(). When this function is called any allocated blocks not required by the current scene state will be deleted so that they may be reused by the application. Additionally, a number of other memory resources are freed by shrinking them to the minimum size required by the scene configuration.</p> +</div> +<div class="section" id="scratch-buffer"> +<h3>Scratch Buffer<a class="headerlink" href="#scratch-buffer" title="Permalink to this headline">¶</a></h3> +<p>A scratch memory block may be passed as a function argument to the function PxScene::simulate. As far as possible, PhysX will internally allocate temporary buffers from the scratch memory block, thereby reducing the need to perform temporary allocations from PxAllocatorCallback. The block may be reused by the application after the PxScene::fetchResults() call, which marks the end of simulation. One restriction on the scratch memory block is that it must be a multiple of 16K, and it must be 16-byte aligned.</p> +</div> +<div class="section" id="in-place-serialization"> +<h3>In-place Serialization<a class="headerlink" href="#in-place-serialization" title="Permalink to this headline">¶</a></h3> +<p>PhysX objects cab be stored in memory owned by the application using PhysX' binary deserialization mechanism. See <a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a> for details.</p> +</div> +<div class="section" id="pvd-integration"> +<h3>PVD Integration<a class="headerlink" href="#pvd-integration" title="Permalink to this headline">¶</a></h3> +<p>Detailed information about memory allocation can be recorded and displayed in the PhysX Visual Debugger. This memory profiling feature can be configured by setting the trackOutstandingAllocations flag when calling PxCreatePhysics(), and raising the flag PxVisualDebuggerConnectionFlag::eMEMORY when connecting to the debugger with PxVisualDebuggerExt::createConnection().</p> +</div> +</div> +<div class="section" id="completion-tasks"> +<h2>Completion Tasks<a class="headerlink" href="#completion-tasks" title="Permalink to this headline">¶</a></h2> +<p>A completion task is a task that executes immediately after PxScene::simulate has exited. If PhysX has been configured to use worker threads then PxScene::simulate will start simulation tasks on the worker threads and will likely exit before the worker threads have completed the work necessary to complete the scene update. As a consequence, a typical completion task would first need to call PxScene::fetchResults(true) to ensure that fetchResults blocks until all worker threads started during simulate() have completed their work. After calling fetchResults(true), the completion task can perform any other post-physics work deemed necessary by the application:</p> +<blockquote> +<div>scene.fetchResults(true); +game.updateA(); +game.updateB(); +... +game.updateZ();</div></blockquote> +<p>The completion task is specified as a function argument in PxScene::simulate. More details can be found in the PhysAPI documentation.</p> +</div> +<div class="section" id="synchronizing-with-other-threads"> +<h2>Synchronizing with Other Threads<a class="headerlink" href="#synchronizing-with-other-threads" title="Permalink to this headline">¶</a></h2> +<p>An important consideration for substepping is that simulate() and fetchResults() are classed as write calls on the scene, and it is therefore illegal to read from or write to a scene while those functions are running. For the simulate() function it is important to make the distinction between running and ongoing. In this context, it is illegal to read or write to a scene before simulate() exits. It is perfectly legal, however, to read or write to a scene after simulate() has exited but before the worker threads that started during the simulate() call have completed their work.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">PhysX does not lock its scene graph, but it will report an error in checked build if it detects that multiple threads make concurrent calls to the same scene, unless they are all read calls.</p> +</div> +</div> +<div class="section" id="substepping"> +<h2>Substepping<a class="headerlink" href="#substepping" title="Permalink to this headline">¶</a></h2> +<p>For reasons of fidelity simulation or better stability it is often desired that the simulation frequency of PhysX be higher than the update rate of the application. The simplest way to do this is just to call simulate() and fetchResults() multiple times:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">substepCount</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> +<span class="p">{</span> + <span class="p">...</span> <span class="n">pre</span><span class="o">-</span><span class="n">simulation</span> <span class="n">work</span> <span class="p">(</span><span class="n">update</span> <span class="n">controllers</span><span class="p">,</span> <span class="n">etc</span><span class="p">)</span> <span class="p">...</span> + <span class="n">scene</span><span class="o">-></span><span class="n">simulate</span><span class="p">(</span><span class="n">substepSize</span><span class="p">);</span> + <span class="n">scene</span><span class="o">-></span><span class="n">fetchResults</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> + <span class="p">...</span> <span class="n">post</span> <span class="n">simulation</span> <span class="n">work</span> <span class="p">(</span><span class="n">process</span> <span class="n">physics</span> <span class="n">events</span><span class="p">,</span> <span class="n">etc</span><span class="p">)</span> <span class="p">...</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Sub-stepping can also be integrated with the completion task feature of the simulate() function. To illustrate this, consider the situation where the scene is simulated until the graphics component signals that it has completed updating the render state of the scene. Here, the completion task will naturally run after simulate() has exited. Its first job will be to block with fetchResults(true) to ensure that it waits until both simulate() and fetchResults() have completed their sequential work. When the completion task is able to proceed its next work item will be to query the graphics component to check if another simulate() is required or if it can exit. In the case that another simulate() step is required it will clearly need to pass a completion task to simulate(). A tricky point here is that a completion task cannot submit itself as the next completion task because it would cause an illegal recursion. A solution to this problem might to be to have two completion tasks where each stores a reference to the other. Each completion task can then pass its partner to simulate():</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="p">.</span><span class="n">fetchResults</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">graphics</span><span class="p">.</span><span class="n">isComplete</span><span class="p">())</span> +<span class="p">{</span> + <span class="n">scene</span><span class="p">.</span><span class="n">simulate</span><span class="p">(</span><span class="n">otherCompletionTask</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="split-sim"> +<h2>Split sim<a class="headerlink" href="#split-sim" title="Permalink to this headline">¶</a></h2> +<p>As an alternative to simulate(), you can split the simulation into two different phases, collide() and advance(). For some properties, called write-through properties, modifications during the collide() phase will be seen immediately by the subsequent advance() phase. This allows collide() to begin before the data required by advance() is available and to run in parallel with game logic that generates inputs to advance(). This is particularly useful for animation logic generating kinematic targets, and for controllers applying forces to bodies. The write-through properties are listed below:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">addForce</span><span class="p">()</span><span class="o">/</span><span class="n">addTorque</span><span class="p">()</span><span class="o">/</span><span class="n">clearForce</span><span class="p">()</span><span class="o">/</span><span class="n">clearTorque</span><span class="p">()</span> +<span class="n">setAngularVelocity</span><span class="p">()</span><span class="o">/</span><span class="n">setLinearVelocity</span><span class="p">()</span> +<span class="n">setKinematicTarget</span><span class="p">()</span> +<span class="n">wakeUp</span><span class="p">()</span> +<span class="n">setWakeCounter</span><span class="p">()</span> +</pre></div> +</div> +<p>When using the split sim, a physics simulation loop would look like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="p">.</span><span class="n">collide</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span> +<span class="n">scene</span><span class="p">.</span><span class="n">fetchCollision</span><span class="p">()</span> +<span class="n">scene</span><span class="p">.</span><span class="n">advance</span><span class="p">()</span> +<span class="n">scene</span><span class="p">.</span><span class="n">fetchResults</span><span class="p">()</span> +</pre></div> +</div> +<p>Any other sequence of API calls is illegal. The SDK will issue error messages. The users can interleave the physics-dependent game logic between collide() and fetchCollision:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="p">.</span><span class="n">collide</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span> +<span class="n">physics</span><span class="o">-</span><span class="n">dependent</span> <span class="n">game</span> <span class="n">logic</span><span class="p">(</span><span class="n">anmimation</span><span class="p">,</span> <span class="n">rendering</span><span class="p">)</span> +<span class="n">scene</span><span class="p">.</span><span class="n">fetchCollision</span><span class="p">()</span> +</pre></div> +</div> +<p>fetchCollision() will wait until collide() has finished before it updates the write-through properties in the SDK. Once fetchCollision() has completed, any state modification performed on the objects in the executing scene will be buffered and will not be reflected until the simulation and a call to fetchResults() has completed. The solver will take the write-through properties into account when computing the new sets of velocities and poses for the actors being simulated.</p> +</div> +<div class="section" id="split-fetchresults"> +<h2>Split fetchResults<a class="headerlink" href="#split-fetchresults" title="Permalink to this headline">¶</a></h2> +<p>The fetchResults() method is available in both a standard and split format. The split format offers some advantages over the standard fetchResult() method because it permits the user to parallelize processing of contact reports, which can be expensive when simulating complex scenes.</p> +<p>A simplistic way to use split fetchResults would look something like this:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">gSharedIndex</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> + +<span class="n">gScene</span><span class="o">-></span><span class="n">simulate</span><span class="p">(</span><span class="mf">1.0f</span> <span class="o">/</span> <span class="mf">60.0f</span><span class="p">);</span> + +<span class="c1">//Call fetchResultsStart. Get the set of pair headers</span> +<span class="k">const</span> <span class="n">PxContactPairHeader</span><span class="o">*</span> <span class="n">pairHeader</span><span class="p">;</span> +<span class="n">PxU32</span> <span class="n">nbContactPairs</span><span class="p">;</span> +<span class="n">gScene</span><span class="o">-></span><span class="n">fetchResultsStart</span><span class="p">(</span><span class="n">pairHeader</span><span class="p">,</span> <span class="n">nbContactPairs</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + +<span class="c1">//Set up continuation task to be run after callbacks have been processed in parallel</span> +<span class="n">callbackFinishTask</span><span class="p">.</span><span class="n">setContinuation</span><span class="p">(</span><span class="o">*</span><span class="n">gScene</span><span class="o">-></span><span class="n">getTaskManager</span><span class="p">(),</span> <span class="nb">NULL</span><span class="p">);</span> +<span class="n">callbackFinishTask</span><span class="p">.</span><span class="n">reset</span><span class="p">();</span> + +<span class="c1">//process the callbacks</span> +<span class="n">gScene</span><span class="o">-></span><span class="n">processCallbacks</span><span class="p">(</span><span class="o">&</span><span class="n">callbackFinishTask</span><span class="p">);</span> + +<span class="n">callbackFinishTask</span><span class="p">.</span><span class="n">removeReference</span><span class="p">();</span> + +<span class="n">callbackFinishTask</span><span class="p">.</span><span class="n">wait</span><span class="p">();</span> + +<span class="n">gScene</span><span class="o">-></span><span class="n">fetchResultsFinish</span><span class="p">();</span> +</pre></div> +</div> +<p>The user is free to use their own task/threading system to process the callbacks. However, the PhysX scene provides a utility function that processes the callbacks using multiple threads, which is used in this code snippet. This method takes a continuation task that will be run when the tasks processing callbacks have completed. In this example, the completion task raises an event that can be waited upon to notify the main thread that callback processing has completed.</p> +<p>This feature is demonstrated in SnippetSplitFetchResults. In order to make use of this approach, contact notification callbacks must be thread-safe. Furthermore, for this approach to be beneficial, contact notification callbacks need to be doing a significant amount of work to benefit from multi-threading them</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Simulation</a><ul> +<li><a class="reference internal" href="#callback-sequence">Callback Sequence</a></li> +<li><a class="reference internal" href="#simulation-memory">Simulation memory</a><ul> +<li><a class="reference internal" href="#scene-limits">Scene Limits</a></li> +<li><a class="reference internal" href="#k-data-blocks">16K Data Blocks</a></li> +<li><a class="reference internal" href="#scratch-buffer">Scratch Buffer</a></li> +<li><a class="reference internal" href="#in-place-serialization">In-place Serialization</a></li> +<li><a class="reference internal" href="#pvd-integration">PVD Integration</a></li> +</ul> +</li> +<li><a class="reference internal" href="#completion-tasks">Completion Tasks</a></li> +<li><a class="reference internal" href="#synchronizing-with-other-threads">Synchronizing with Other Threads</a></li> +<li><a class="reference internal" href="#substepping">Substepping</a></li> +<li><a class="reference internal" href="#split-sim">Split sim</a></li> +<li><a class="reference internal" href="#split-fetchresults">Split fetchResults</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="RigidBodyDynamics.html" + title="previous chapter">Rigid Body Dynamics</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="AdvancedCollisionDetection.html" + title="next chapter">Advanced Collision Detection</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" /> + <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="AdvancedCollisionDetection.html" title="Advanced Collision Detection" + >next</a></li> + <li class="right" > + <a href="RigidBodyDynamics.html" title="Rigid Body Dynamics" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/SpatialQueries.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/SpatialQueries.html new file mode 100644 index 00000000..250dce9b --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/SpatialQueries.html @@ -0,0 +1,166 @@ +<!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>Spatial Queries — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Scene Queries" href="SceneQueries.html" /> + <link rel="prev" title="Geometry Queries" href="GeometryQueries.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="SceneQueries.html" title="Scene Queries" + accesskey="N">next</a></li> + <li class="right" > + <a href="GeometryQueries.html" title="Geometry Queries" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="spatial-queries"> +<span id="spatialqueries"></span><h1>Spatial Queries<a class="headerlink" href="#spatial-queries" title="Permalink to this headline">¶</a></h1> +<p>Applications commonly need to efficiently query volumes in space or trace rays or moving objects through space to determine what might be there. PhysX supports two interfaces for this, one for objects already in a scene, and one for querying against sets of arbitrary AABBs. The scene query system is discussed in <a class="reference internal" href="SceneQueries.html#scenequeries"><em>Scene Queries</em></a>.</p> +<div class="section" id="pxspatialindex"> +<h2>PxSpatialIndex<a class="headerlink" href="#pxspatialindex" title="Permalink to this headline">¶</a></h2> +<p>PxSpatialIndex is a BVH data structure that allows spatial queries to be performed without the need to instantiate a PxScene. +It supports insertion, removal and updating of any objects defining a bounding box, and raycasts, sweeps, and overlap queries +against those bounds.</p> +<p>Spatial index has been marked as deprecated in 3.4 and will be removed in future releases.</p> +<p>SnippetSpatialIndex shows an example of how to use this class.</p> +<p>PxSpatialIndex has no internal locking, and there are special considerations when using it from multiple threads. +Query operations (marked const in the interface) must not be issued in parallel with update (non-const) operations, +or update operations in parallel with each other. When issuing query operations in parallel, +it is important to be aware that PxSpatialIndex defers some updates to its internal data structures until a query is issued. +In a single-threaded context this does not affect correctness or safety, but when querying from multiple threads simultaneously +the internal updates may cause data hazards. In order to avoid these, call the flush() method to force the updates +to be processed immediately. Between a call to flushUpdates() and any subsequent update operation, queries may be safely issued in parallel.</p> +<p>A query against a PxSpatialIndex structure will result in a callback for each AABB hit by the query, allowing filtering or precise intersection as desired. The methods in the PxGeometryQuery class can be used to perform these intersection tests. Results will typically be in approximately sorted order, and when looking for the closest object in a raycast or sweep query against PxSpatialIndex, a useful optimization is to clip the length of the query inside the callback. +For example, in SnippetSpatialIndex:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxAgain</span> <span class="nf">onHit</span><span class="p">(</span><span class="n">PxSpatialIndexItem</span><span class="o">&</span> <span class="n">item</span><span class="p">,</span> <span class="n">PxReal</span> <span class="n">distance</span><span class="p">,</span> <span class="n">PxReal</span><span class="o">&</span> <span class="n">shrunkDistance</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">distance</span><span class="p">);</span> + + <span class="n">Sphere</span><span class="o">&</span> <span class="n">s</span> <span class="o">=</span> <span class="k">static_cast</span><span class="o"><</span><span class="n">Sphere</span><span class="o">&></span><span class="p">(</span><span class="n">item</span><span class="p">);</span> + <span class="n">PxRaycastHit</span> <span class="n">hitData</span><span class="p">;</span> + + <span class="c1">// the ray hit the sphere's AABB, now we do a ray-sphere intersection test to find out if</span> + <span class="c1">// the ray hit the sphere</span> + + <span class="n">PxU32</span> <span class="n">hit</span> <span class="o">=</span> <span class="n">PxGeometryQuery</span><span class="o">::</span><span class="n">raycast</span><span class="p">(</span><span class="n">position</span><span class="p">,</span> <span class="n">direction</span><span class="p">,</span> + <span class="n">PxSphereGeometry</span><span class="p">(</span><span class="n">s</span><span class="p">.</span><span class="n">radius</span><span class="p">),</span> <span class="n">PxTransform</span><span class="p">(</span><span class="n">s</span><span class="p">.</span><span class="n">position</span><span class="p">),</span> + <span class="mf">1e6</span><span class="p">,</span> <span class="n">PxHitFlag</span><span class="o">::</span><span class="n">eDEFAULT</span><span class="p">,</span> + <span class="mi">1</span><span class="p">,</span> <span class="o">&</span><span class="n">hitData</span><span class="p">);</span> + + <span class="c1">// if the raycast hit and it's closer than what we had before, shrink the maximum length</span> + <span class="c1">// of the raycast</span> + + <span class="k">if</span><span class="p">(</span><span class="n">hit</span> <span class="o">&&</span> <span class="n">hitData</span><span class="p">.</span><span class="n">distance</span> <span class="o"><</span> <span class="n">closest</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">closest</span> <span class="o">=</span> <span class="n">hitData</span><span class="p">.</span><span class="n">distance</span><span class="p">;</span> + <span class="n">hitSphere</span> <span class="o">=</span> <span class="o">&</span><span class="n">s</span><span class="p">;</span> + <span class="n">shrunkDistance</span> <span class="o">=</span> <span class="n">hitData</span><span class="p">.</span><span class="n">distance</span><span class="p">;</span> + <span class="p">}</span> + + <span class="c1">// and continue the query</span> + + <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Methods in PxGeometryQuery may report positive results when shapes are within a numerical tolerance of intersection or impact. +To obtain results that are identical when using PxSpatialIndex and when not using a culling hierarchy, the bounding boxes must be slightly padded. +PxGeometryQuery::getWorldBounds adds this padding by default.</p> +</div> +<p>PxSpatialIndex has the same performance characteristics as the scene query system using the PxPruningStructureType::eDYNAMIC_AABB_TREE option. If the AABBs correspond to moving objects, or there are many insertions and deletions, the quality of the tree may degrade over time. In order to prevent this, the tree may be rebuilt entirely using the function <em>rebuildFull()</em>. Alternatively, a second tree may be built incrementally in the background over many small steps, using the function <em>rebuildStep()</em> to performs the same incremental rebuild step as performed by the scene's dynamic pruning structure during <em>fetchResults()</em>. See <a class="reference internal" href="SceneQueries.html#pxpruningstructuretype"><em>PxPruningStructureType</em></a> for details.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Spatial Queries</a><ul> +<li><a class="reference internal" href="#pxspatialindex">PxSpatialIndex</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="GeometryQueries.html" + title="previous chapter">Geometry Queries</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="SceneQueries.html" + title="next chapter">Scene Queries</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" /> + <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="SceneQueries.html" title="Scene Queries" + >next</a></li> + <li class="right" > + <a href="GeometryQueries.html" title="Geometry Queries" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Startup.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Startup.html new file mode 100644 index 00000000..9e406285 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Startup.html @@ -0,0 +1,277 @@ +<!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>Startup and Shutdown — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Threading" href="Threading.html" /> + <link rel="prev" title="The PhysX API" href="API.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Threading.html" title="Threading" + accesskey="N">next</a></li> + <li class="right" > + <a href="API.html" title="The PhysX API" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="startup-and-shutdown"> +<span id="startup"></span><h1>Startup and Shutdown<a class="headerlink" href="#startup-and-shutdown" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>The first step in using the PhysX SDK in a program is the initialization of some global objects. These objects can be released when PhysX is no longer needed to free resources. This chapter describes how to do this.</p> +</div> +<div class="section" id="foundation-and-physics"> +<h2>Foundation and Physics<a class="headerlink" href="#foundation-and-physics" title="Permalink to this headline">¶</a></h2> +<p>First, in some startup code, create a <em>PxFoundation</em> object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">PxDefaultErrorCallback</span> <span class="n">gDefaultErrorCallback</span><span class="p">;</span> +<span class="k">static</span> <span class="n">PxDefaultAllocator</span> <span class="n">gDefaultAllocatorCallback</span><span class="p">;</span> + +<span class="n">mFoundation</span> <span class="o">=</span> <span class="n">PxCreateFoundation</span><span class="p">(</span><span class="n">PX_FOUNDATION_VERSION</span><span class="p">,</span> <span class="n">gDefaultAllocatorCallback</span><span class="p">,</span> + <span class="n">gDefaultErrorCallback</span><span class="p">);</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">mFoundation</span><span class="p">)</span> + <span class="n">fatalError</span><span class="p">(</span><span class="s">"PxCreateFoundation failed!"</span><span class="p">);</span> +</pre></div> +</div> +<p>Every PhysX module requires a PxFoundation instance to be available. The required parameters are a version ID, an allocator callback and an error callback. <em>PX_PHYSICS_VERSION</em>, is a macro predefined in our headers to enable PhysX to check for a version mismatch between the headers and the corresponding SDK DLLs.</p> +<p>Usually, the allocator callback and error callback are specific to the application, but PhysX provides default implementations that make it easy to get started. See <a class="reference internal" href="API.html#memorymanagement"><em>Memory Management</em></a> and <a class="reference internal" href="API.html#errorreporting"><em>Error Reporting</em></a> for more details of these callbacks. (The actual sample code supports an advanced memory allocator that tracks allocations instead of the default, but we have omitted that detail here.)</p> +<p>Now create the top-level <em>PxPhysics</em> object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">recordMemoryAllocations</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span> + +<span class="n">mPvd</span> <span class="o">=</span> <span class="n">PxCreatePvd</span><span class="p">(</span><span class="o">*</span><span class="n">gFoundation</span><span class="p">);</span> +<span class="n">PxPvdTransport</span><span class="o">*</span> <span class="n">transport</span> <span class="o">=</span> <span class="n">PxDefaultPvdSocketTransportCreate</span><span class="p">(</span><span class="n">PVD_HOST</span><span class="p">,</span> <span class="mi">5425</span><span class="p">,</span> <span class="mi">10</span><span class="p">);</span> +<span class="n">mPvd</span><span class="o">-></span><span class="n">connect</span><span class="p">(</span><span class="o">*</span><span class="n">transport</span><span class="p">,</span><span class="n">PxPvdInstrumentationFlag</span><span class="o">::</span><span class="n">eALL</span><span class="p">);</span> + + +<span class="n">mPhysics</span> <span class="o">=</span> <span class="n">PxCreatePhysics</span><span class="p">(</span><span class="n">PX_PHYSICS_VERSION</span><span class="p">,</span> <span class="o">*</span><span class="n">mFoundation</span><span class="p">,</span> + <span class="n">PxTolerancesScale</span><span class="p">(),</span> <span class="n">recordMemoryAllocations</span><span class="p">,</span> <span class="n">mPvd</span><span class="p">);</span> +<span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">mPhysics</span><span class="p">)</span> + <span class="n">fatalError</span><span class="p">(</span><span class="s">"PxCreatePhysics failed!"</span><span class="p">);</span> +</pre></div> +</div> +<p>Again, the version ID has to be passed in. The PxTolerancesScale parameter makes it easier to author content at different scales and still have PhysX work as expected, but to get started simply pass a default object of this type. The recordMemoryAllocations parameter specifies whether to perform memory profiling. The optional PVD instance enables the debugging and profiling with the PhysX Visual Debugger.</p> +</div> +<div class="section" id="cooking"> +<h2>Cooking<a class="headerlink" href="#cooking" title="Permalink to this headline">¶</a></h2> +<p>The PhysX cooking library provides utilities for creating, converting, and serializing bulk data. Depending on your application, you may wish to link to the cooking library in order to process such data at runtime. Alternatively you may be able to process all such data in advance and just load it into memory as required. Initialize the cooking library as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mCooking</span> <span class="o">=</span> <span class="n">PxCreateCooking</span><span class="p">(</span><span class="n">PX_PHYSICS_VERSION</span><span class="p">,</span> <span class="o">*</span><span class="n">mFoundation</span><span class="p">,</span> <span class="n">PxCookingParams</span><span class="p">(</span><span class="n">scale</span><span class="p">));</span> +<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">mCooking</span><span class="p">)</span> + <span class="n">fatalError</span><span class="p">(</span><span class="s">"PxCreateCooking failed!"</span><span class="p">);</span> +</pre></div> +</div> +<p>The PxCookingParams struct configures the cooking library to target different platforms, use non-default tolerances or produce optional outputs. It is important to use consistent PxTolerancesScale values everywhere in your application (see <a class="reference internal" href="API.html#pxtolerancescale"><em>Using Different Units</em></a> for more details).</p> +<p>The cooking library generates data through a streaming interface. In the samples, implementations of streams are provided in the PxToolkit library to read and write from files and memory buffers. Heightfield or Trianglemesh cooked meshes can be directly inserted into PxPhysics without serialization using the PxPhysicsInsertionCallback. The default callback must be used and can be obtained using the PxPhysics::getPhysicsInsertionCallback().</p> +</div> +<div class="section" id="extensions"> +<h2>Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h2> +<p>The extensions library contains many functions that may be useful to a large class of users, but which some users may prefer to omit from their application either for code size reasons or to avoid use of certain subsystems, such as those pertaining to networking. Initializing the extensions library requires the PxPhysics object:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PxInitExtensions</span><span class="p">(</span><span class="o">*</span><span class="n">mPhysics</span><span class="p">,</span> <span class="n">mPvd</span><span class="p">))</span> + <span class="n">fatalError</span><span class="p">(</span><span class="s">"PxInitExtensions failed!"</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="optional-sdk-components"> +<span id="optionalsdkcomponents"></span><h2>Optional SDK Components<a class="headerlink" href="#optional-sdk-components" title="Permalink to this headline">¶</a></h2> +<p>When linking PhysX as a static library on memory constrained platforms, it is possible to avoid linking the code of some PhysX features that are not always used in order to save memory. Currently the optional features are:</p> +<blockquote> +<div><ul class="simple"> +<li>Articulations</li> +<li>Height Fields</li> +<li>Cloth</li> +<li>Particles</li> +</ul> +</div></blockquote> +<p>If your application requires a subset of this functionality, it is recommended that you call PxCreateBasePhysics as opposed to PxCreatePhysics and then manually register the components you require. Below is an example that registers some of the options:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">physx</span><span class="o">::</span><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">customCreatePhysics</span><span class="p">(</span><span class="n">physx</span><span class="o">::</span><span class="n">PxU32</span> <span class="n">version</span><span class="p">,</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxFoundation</span><span class="o">&</span> <span class="n">foundation</span><span class="p">,</span> + <span class="k">const</span> <span class="n">physx</span><span class="o">::</span><span class="n">PxTolerancesScale</span><span class="o">&</span> <span class="n">scale</span><span class="p">,</span> + <span class="kt">bool</span> <span class="n">trackOutstandingAllocations</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxPvd</span><span class="o">*</span> <span class="n">pvd</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">physx</span><span class="o">::</span><span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span> <span class="o">=</span> <span class="n">PxCreateBasePhysics</span><span class="p">(</span><span class="n">version</span><span class="p">,</span> <span class="n">foundation</span><span class="p">,</span> <span class="n">scale</span><span class="p">,</span> + <span class="n">trackOutstandingAllocations</span><span class="p">,</span> <span class="n">pvd</span><span class="p">);</span> + + <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">physics</span><span class="p">)</span> + <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span> + + <span class="n">PxRegisterArticulations</span><span class="p">(</span><span class="o">*</span><span class="n">physics</span><span class="p">);</span> + <span class="n">PxRegisterHeightFields</span><span class="p">(</span><span class="o">*</span><span class="n">physics</span><span class="p">);</span> + + <span class="k">return</span> <span class="n">physics</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Note that this will only save memory when linking PhysX as a static library, as we rely on the linker to strip out the unused code.</p> +</div> +<div class="section" id="delay-loading-dlls"> +<h2>Delay-Loading DLLs<a class="headerlink" href="#delay-loading-dlls" title="Permalink to this headline">¶</a></h2> +<p>The PhysXCommon DLL, PxFoundation DLL and PxPvdSDK DLL are marked as delay-loaded inside of the PhysX, PhysXCooking, PhysXCommon and PxPvdSDK projects. So it is possible to have delay-loaded PxFoundation, PxPvdSDK, PhysXCommon, PhysX and PhysXCooking DLLs.</p> +<div class="section" id="physxcommon-dll-and-psfoundation-dll-load"> +<h3>PhysXCommon DLL and PsFoundation DLL load<a class="headerlink" href="#physxcommon-dll-and-psfoundation-dll-load" title="Permalink to this headline">¶</a></h3> +<p>The application links against PhysXCommon DLL, and will usually load PxFoundation.dll, PxPvdSDK and PhysXCommon.dll before any other PhysX DLL. The DLL loaded by the application must be the same one that will be used by the PhysX and PhysXCooking DLLs. In the PhysX and PhysXCooking DLLs, the choice of PhysXCommon, PxFoundation and PxPvdSDK is made as follows:</p> +<blockquote> +<div><ul class="simple"> +<li>If delay load hook is specified the PhysXCommon name, PxFoundation or PxPvdSDK name provided by user is used</li> +<li>If delay load hook is not specified, the corresponding PhysXCommon DLL, PsFoundation DLL or PxPvdSDK DLL is used</li> +</ul> +</div></blockquote> +</div> +<div class="section" id="pxdelayloadhook"> +<h3>PxDelayLoadHook<a class="headerlink" href="#pxdelayloadhook" title="Permalink to this headline">¶</a></h3> +<p>The PxDelayLoadHook class supports loading of different versions of PhysXCommon DLL, PxFoundation DLL or PxPvdSDK DLL. This can be achieved by providing different DLL names to the PhysX SDK through a custom subclass of PxDelayLoadHook, see the following example:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">SampleDelayLoadHook</span><span class="o">:</span> <span class="k">public</span> <span class="n">PxDelayLoadHook</span> +<span class="p">{</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPhysXCommonDEBUGDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PhysX3CommonDEBUG_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPhysXCommonCHECKEDDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PhysX3CommonCHECKED_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPhysXCommonPROFILEDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PhysX3CommonPROFILE_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPhysXCommonDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PhysX3Common_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxFoundationDEBUGDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxFoundationDEBUG_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxFoundationCHECKEDDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxFoundationCHECKED_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxFoundationPROFILEDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxFoundationPROFILE_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxFoundationDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxFoundation_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxPvdSDKDEBUGDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxPvdSDKDEBUG_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxPvdSDKCHECKEDDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxPvdSDKCHECKED_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxPvdSDKPROFILEDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxPvdSDKPROFILE_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getPxPvdSDKDllName</span><span class="p">()</span> <span class="k">const</span> + <span class="p">{</span> <span class="k">return</span> <span class="s">"PxPvdSDK_x64_Test.dll"</span><span class="p">;</span> <span class="p">}</span> +<span class="p">}</span> <span class="n">gDelayLoadHook</span><span class="p">;</span> +</pre></div> +</div> +<p>Now the hook must be set for PhysX, PhysXCooking, PhysXGpu, PhysXCommon, PxPvdSDK:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxSetPhysXDelayLoadHook</span><span class="p">(</span><span class="o">&</span><span class="n">gDelayLoadHook</span><span class="p">);</span> +<span class="n">PxSetPhysXCookingDelayLoadHook</span><span class="p">(</span><span class="o">&</span><span class="n">gDelayLoadHook</span><span class="p">);</span> +<span class="n">PxSetPhysXGpuDelayLoadHook</span><span class="p">(</span><span class="o">&</span><span class="n">gDelayLoadHook</span><span class="p">);</span> +<span class="n">PxSetPhysXCommonDelayLoadHook</span><span class="p">(</span><span class="o">&</span><span class="n">gDelayLoadHook</span><span class="p">);</span> +<span class="n">PxPvdSetFoundationDelayLoadHook</span><span class="p">(</span><span class="o">&</span><span class="n">gDelayLoadHook</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="physxcommon-secure-load"> +<h3>PhysXCommon Secure Load<a class="headerlink" href="#physxcommon-secure-load" title="Permalink to this headline">¶</a></h3> +<p>All PhysX DLLs distributed by NVIDIA are signed. The PhysXCommon DLL signature is checked, when it is loaded by PhysX or PhysXCooking. If signature test fails the application is terminated.</p> +</div> +</div> +<div class="section" id="shutting-down"> +<h2>Shutting Down<a class="headerlink" href="#shutting-down" title="Permalink to this headline">¶</a></h2> +<p>To dispose of any PhysX object, call its release() method. This will destroy the object, and all contained objects. The precise behavior depends on the object type being released, so refer to the reference guide for details. To shut down the extensions library, call the function <em>PxCloseExtensions()</em>. To shut down physics, call release() on the PxPhysics object, and this will clean up all of the physics objects:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mPhysics</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>Do not forget to release the foundation object as well, but only after all other PhysX modules have been released:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mFoundation</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Startup and Shutdown</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#foundation-and-physics">Foundation and Physics</a></li> +<li><a class="reference internal" href="#cooking">Cooking</a></li> +<li><a class="reference internal" href="#extensions">Extensions</a></li> +<li><a class="reference internal" href="#optional-sdk-components">Optional SDK Components</a></li> +<li><a class="reference internal" href="#delay-loading-dlls">Delay-Loading DLLs</a><ul> +<li><a class="reference internal" href="#physxcommon-dll-and-psfoundation-dll-load">PhysXCommon DLL and PsFoundation DLL load</a></li> +<li><a class="reference internal" href="#pxdelayloadhook">PxDelayLoadHook</a></li> +<li><a class="reference internal" href="#physxcommon-secure-load">PhysXCommon Secure Load</a></li> +</ul> +</li> +<li><a class="reference internal" href="#shutting-down">Shutting Down</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="API.html" + title="previous chapter">The PhysX API</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Threading.html" + title="next chapter">Threading</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" /> + <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="Threading.html" title="Threading" + >next</a></li> + <li class="right" > + <a href="API.html" title="The PhysX API" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Statistics.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Statistics.html new file mode 100644 index 00000000..cbbacb23 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Statistics.html @@ -0,0 +1,129 @@ +<!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>Simulation Statistics — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Serialization" href="Serialization.html" /> + <link rel="prev" title="PhysX Visual Debugger (PVD)" href="VisualDebugger.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Serialization.html" title="Serialization" + accesskey="N">next</a></li> + <li class="right" > + <a href="VisualDebugger.html" title="PhysX Visual Debugger (PVD)" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="simulation-statistics"> +<span id="statistics"></span><h1>Simulation Statistics<a class="headerlink" href="#simulation-statistics" title="Permalink to this headline">¶</a></h1> +<div class="section" id="interface"> +<h2>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">¶</a></h2> +<p>In this chapter we will have a quick look at the statistics information that PhysX collects every simulation step. Usually, this information can be explored in the PhysX Visual Debugger but we do offer a PhysX API method as well to allow applications to access the data directly. After a simulation step and a call to <em>PxScene::fetchResults()</em>, the simulation statistics for the processed step can be retrieved through the <em>PxScene::getSimulationStatistics()</em> interface. The method copies the data to a user provided <em>PxSimulationStatistics</em> structure. For details about the individual members please refer to the API documentation.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Do not fetch the simulation statistics while the simulation is running.</p> +</div> +</div> +<div class="section" id="usage"> +<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2> +<p>The provided simulation statistics is mainly meant to help investigate performance issues. It provides a quantitative summary of the work done, i.e., the number of objects or combination of objects which have been processed in the current simulation step. For example, if you encounter performance spikes in certain frames, then the simulation statistics might give some insight into possible causes. For instance:</p> +<ul class="simple"> +<li>Has a large amount of volumes been added or removed from the broadphase in one single step? You could try to distribute the addition/removal of objects over a couple of simulation steps or maybe there is a particle system in the scene whose grid size is very small.</li> +<li>Are there suddenly many more collision pairs processed than expected? This could be caused by a badly configured collision pair filter or maybe some <em>PxPairFlags</em> have been accidentally raised.</li> +<li>etc.</li> +</ul> +<p>Please keep in mind that the simulation statistics are currently less a measurement of what the scene contains but rather what got processed. So it is only partially helpful to detect whether objects have been configured and arranged properly.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Simulation Statistics</a><ul> +<li><a class="reference internal" href="#interface">Interface</a></li> +<li><a class="reference internal" href="#usage">Usage</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="VisualDebugger.html" + title="previous chapter">PhysX Visual Debugger (PVD)</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Serialization.html" + title="next chapter">Serialization</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" /> + <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="Serialization.html" title="Serialization" + >next</a></li> + <li class="right" > + <a href="VisualDebugger.html" title="PhysX Visual Debugger (PVD)" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Threading.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Threading.html new file mode 100644 index 00000000..bddc6f48 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Threading.html @@ -0,0 +1,454 @@ +<!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>Threading — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Geometry" href="Geometry.html" /> + <link rel="prev" title="Startup and Shutdown" href="Startup.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Geometry.html" title="Geometry" + accesskey="N">next</a></li> + <li class="right" > + <a href="Startup.html" title="Startup and Shutdown" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="threading"> +<span id="id1"></span><h1>Threading<a class="headerlink" href="#threading" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>This chapter explains how to use PhysX in multithreaded applications. There are three main aspects to using PhysX with multiple threads:</p> +<ul class="simple"> +<li>how to make read and write calls into the PhysX API from multiple threads without causing race conditions.</li> +<li>how to use multiple threads to accelerate simulation processing.</li> +<li>how to perform asynchronous simulation, and read and write to the API while simulation is being processed.</li> +</ul> +</div> +<div class="section" id="data-access-from-multiple-threads"> +<span id="dataaccessrules"></span><h2>Data Access from Multiple Threads<a class="headerlink" href="#data-access-from-multiple-threads" title="Permalink to this headline">¶</a></h2> +<p>For efficiency reasons, PhysX does not internally lock access to its data structures by the application, so be careful when calling the API from multiple application threads. The rules are as follows:</p> +<ul class="simple"> +<li>API interface methods marked 'const' are read calls, other API interface methods are write calls.</li> +<li>API read calls may be made simultaneously from multiple threads.</li> +<li>Objects in different scenes may be safely accessed by different threads.</li> +<li>Different objects outside a scene may be safely accessed from different threads. Be aware that accessing an object may indirectly cause access to another object via a persistent reference (such as joints and actors referencing one another, an actor referencing a shape, or a shape referencing a mesh.)</li> +</ul> +<p>Access patterns which do not conform to the above rules may result in data corruption, deadlocks, or crashes. Note in particular that it is not legal to perform a write operation on an object in a scene concurrently with a read operation to an object in the same scene. The checked build contains code which tracks access by application threads to objects within a scene, to try and detect problems at the point when the illegal API call is made.</p> +<div class="section" id="scene-locking"> +<h3>Scene Locking<a class="headerlink" href="#scene-locking" title="Permalink to this headline">¶</a></h3> +<p>Each PxScene object provides a multiple reader, single writer lock that can be used to control access to the scene by multiple threads. This is useful for situations where the PhysX scene is +shared between more than one system, for example APEX and a game engine's physics code. The scene lock provides a way for these systems to coordinate with each other.</p> +<p>It is not mandatory to use the lock. If all access to the scene is from a single thread, using the lock adds unnecessary overhead. Even if you are accessing the scene from multiple threads, you may be able to synchronize the threads using a simpler or more efficient application-specific mechanism that guarantees your application meets the above conditions. However, using the scene lock has two potential benefits:</p> +<ul class="simple"> +<li>If the <em>PxSceneFlag::eREQUIRE_RW_LOCK</em> is set, the checked build will issue a warning for any API call made without first acquiring the lock, or if a write call is made when the lock has only been acquired for read,</li> +<li>The APEX SDK uses the scene lock to ensure that it shares the scene safely with your application.</li> +</ul> +<p>There are four methods for for acquiring / releasing the lock:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxScene</span><span class="o">::</span><span class="n">lockRead</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">file</span><span class="o">=</span><span class="nb">NULL</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">line</span><span class="o">=</span><span class="mi">0</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxScene</span><span class="o">::</span><span class="n">unlockRead</span><span class="p">();</span> + +<span class="kt">void</span> <span class="n">PxScene</span><span class="o">::</span><span class="n">lockWrite</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">file</span><span class="o">=</span><span class="nb">NULL</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">line</span><span class="o">=</span><span class="mi">0</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxScene</span><span class="o">::</span><span class="n">unlockWrite</span><span class="p">();</span> +</pre></div> +</div> +<p>Additionally there is an RAII helper class to manage these locks, see PxSceneLock.h.</p> +</div> +<div class="section" id="locking-semantics"> +<h3>Locking Semantics<a class="headerlink" href="#locking-semantics" title="Permalink to this headline">¶</a></h3> +<p>There are precise rules regarding the usage of the scene lock:</p> +<ul class="simple"> +<li>Multiple threads may read at the same time.</li> +<li>Only one thread may write at a time, no thread may write if any threads are reading.</li> +<li>If a thread holds a write lock then it may call both read and write API methods.</li> +<li>Re-entrant read locks are supported, meaning a <em>lockRead()</em> on a thread that has already acquired a read lock is permitted. Each <em>lockRead()</em> must have a paired <em>unlockRead()</em>.</li> +<li>Re-entrant write locks are supported, meaning a <em>lockWrite()</em> on a thread that has already acquired a write lock is permitted. Each <em>lockWrite()</em> must have a paired <em>unlockWrite()</em>.</li> +<li>Calling <em>lockRead()</em> by a thread that has already acquired the write lock is permitted and the thread will continue to have read and write access. Each lock*() must have an associated unlock*() that occurs in reverse order.</li> +<li>Lock upgrading is <em>not</em> supported - a <em>lockWrite()</em> by a thread that has already acquired a read lock is <em>not</em> permitted. Attempting this in checked builds will result in an error, in release builds it will lead to deadlock.</li> +<li>Writers are favored - if a thread attempts a <em>lockWrite()</em> while the read lock is acquired it will be blocked until all readers leave. If new readers arrive while the writer thread is blocked they will be put to sleep and the writer will have first chance to access the scene. This prevents writers being starved in the presence of multiple readers.</li> +<li>If multiple writers are queued then the first writer will receive priority, subsequent writers will be granted access according to OS scheduling.</li> +</ul> +<p>Note: <em>PxScene::release()</em> automatically attempts to acquire the write lock, it is not necessary to acquire it manually before calling release().</p> +</div> +<div class="section" id="locking-best-practices"> +<h3>Locking Best Practices<a class="headerlink" href="#locking-best-practices" title="Permalink to this headline">¶</a></h3> +<p>It is often useful to arrange your application to acquire the lock a single time to perform multiple operations. This minimizes the overhead of the lock, and in addition can prevent cases such as a sweep test in one thread seeing a rag doll that has been only partially inserted by another thread.</p> +<p>Clustering writes can also help reduce contention for the lock, as acquiring the lock for write will stall any other thread trying to perform a read access.</p> +</div> +</div> +<div class="section" id="asynchronous-simulation"> +<h2>Asynchronous Simulation<a class="headerlink" href="#asynchronous-simulation" title="Permalink to this headline">¶</a></h2> +<p>PhysX simulation is asynchronous by default. Start simulation by calling:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">simulate</span><span class="p">(</span><span class="n">dt</span><span class="p">);</span> +</pre></div> +</div> +<p>When this call returns, the simulation step has begun in a separate thread. While simulation is running, you can still make calls into the API. Where those calls affect simulation state, the results will be buffered and reconciled with the simulation results when the simulation step completes.</p> +<p>To wait until simulation completes, call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">scene</span><span class="o">-></span><span class="n">fetchResults</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>The boolean parameter to fetchResults denotes whether the call should wait for simulation to complete, or return immediately with the current completion status. See the API documentation for more detail.</p> +<p>It is important to distinguish two time slots for data access:</p> +<ol class="arabic simple"> +<li>After the call to <em>PxScene::fetchResults()</em> has returned and before the next <em>PxScene::simulate()</em> call (see figure below, blue area "1").</li> +<li>After the call to <em>PxScene::simulate()</em> has returned and before the corresponding <em>PxScene::fetchResults()</em> call (see figure below, green area "2").</li> +</ol> +<a class="reference internal image-reference" href="../_images/timeSlots.png"><img alt="../_images/timeSlots.png" src="../_images/timeSlots.png" style="width: 800px;" /></a> +<p>In the first time slot, the simulation is not running and there are no restrictions for reading or writing object properties. Changes to the position of an object, for example, are applied instantaneously and the next scene query or simulation step will take the new state into account.</p> +<p>In the second time slot the simulation is running and in the process, reading and changing the state of objects. Concurrent access from the user might corrupt the state of the objects or lead to data races or inconsistent views in the simulation code. Hence the simulation code's view of the objects is protected from API writes, and any attributes the simulation updates are buffered to allow API reads. The consequences will be discussed in detail in the next section.</p> +<p>Note that <em>simulate()</em> and <em>fetchResults()</em> are write calls on the scene, and as such it is illegal to access any object in the scene while these functions are running.</p> +<div class="section" id="double-buffering"> +<span id="doublebuffering"></span><h3>Double Buffering<a class="headerlink" href="#double-buffering" title="Permalink to this headline">¶</a></h3> +<p>While a simulation is running, PhysX supports read and write access to objects in the scene (with some exceptions, see further below). This includes adding/removing them to/from a scene.</p> +<p>From the user perspective, API changes are reflected immediately. For example, if the velocity of a rigid body is set and then queried, the new velocity will be returned. Similarly, if an object is created while the simulation is running, it can be accessed/modified as any other object. However, these changes are buffered so that the simulation code sees the object state as it was when <em>PxScene::simulate()</em> was called. For instance, changes to the filter data of an object while the simulation is running are ignored for collision pair generation of the running step, and will only affect for the next simulation step.</p> +<p>When <em>PxScene::fetchResults()</em> is called, any buffered changes are flushed: changes made by the simulation are reflected in API view of the objects, and API changes are made visible to the simulation code for the next step. User changes take precedence: for example, a user change to the position of an object while the simulation is running will overwrite the position which resulted from the simulation.</p> +<p>The delayed application of updates does not affect scene queries, which always take into account the latest changes.</p> +</div> +<div class="section" id="events-involving-removed-objects"> +<h3>Events involving removed objects<a class="headerlink" href="#events-involving-removed-objects" title="Permalink to this headline">¶</a></h3> +<p>Deleting objects or removing them from the scene while the simulation is in process will affect the simulation events sent out at <em>PxScene::fetchResults()</em>. The behavior is as follows:</p> +<ul class="simple"> +<li><em>PxSimulationEventCallback::onWake(), ::onSleep()</em> events will not get fired if an object is involved which got deleted/removed during the running simulation.</li> +<li><em>PxSimulationEventCallback::onContact(), ::onTrigger()</em> events will get fired if an object is involved which got deleted/removed during the running simulation. The deleted/removed object will be marked as such (see <em>PxContactPairHeaderFlag::eREMOVED_ACTOR_0</em>, <em>PxContactPairFlag::eREMOVED_SHAPE_0, PxTriggerPairFlag::eREMOVED_SHAPE_TRIGGER</em>). Furthermore, if <em>PxPairFlag::eNOTIFY_TOUCH_LOST, ::eNOTIFY_THRESHOLD_FORCE_LOST</em> events were requested for the pair containing the deleted/removed object, then these events will be created.</li> +</ul> +</div> +<div class="section" id="support"> +<h3>Support<a class="headerlink" href="#support" title="Permalink to this headline">¶</a></h3> +<p>Not all PhysX objects have full buffering support. Operations which can not run while the simulation is in process are mentioned in the API documentation and the SDK aborts such operations and reports an error. The most important exceptions are as follows:</p> +<ul class="simple"> +<li>Particles: The particle bulk data can not be read or modified while the simulation is running, this includes operations like reading/writing particle positions/velocities, creating/deleting particles, adding forces, etc.</li> +<li>Cloth: The only allowed double buffered operation is to create/delete a cloth and add/remove it to/from the scene.</li> +</ul> +</div> +<div class="section" id="memory-considerations"> +<h3>Memory Considerations<a class="headerlink" href="#memory-considerations" title="Permalink to this headline">¶</a></h3> +<p>The buffers to store the object changes while the simulation is running are created on demand. If memory usage concerns outweigh the advantage of reading/writing objects in parallel with simulation, do not write to objects while the simulation is running.</p> +</div> +</div> +<div class="section" id="multithreaded-simulation"> +<span id="taskman"></span><h2>Multithreaded Simulation<a class="headerlink" href="#multithreaded-simulation" title="Permalink to this headline">¶</a></h2> +<p>PhysX includes a task system for managing CPU and GPU compute resources. Tasks are created with dependencies so +that they are resolved in a given order, when ready they are then submitted to a +user-implemented dispatcher for execution.</p> +<p>Middleware products typically do not want to create CPU threads for their +own use. This is especially true on consoles where execution threads +can have significant overhead. In the task model, the computational +work is broken into jobs that are submitted to the game's thread pool as +they become ready to run.</p> +<p>The following classes comprise the CPU task management.</p> +<div class="section" id="taskmanager"> +<h3>TaskManager<a class="headerlink" href="#taskmanager" title="Permalink to this headline">¶</a></h3> +<p>A TaskManager manages inter-task dependencies and dispatches ready tasks +to their respective dispatcher. There is a dispatcher for CPU tasks and +GPU tasks assigned to the TaskManager.</p> +<p>TaskManagers are owned and created by the SDK. Each PxScene will allocate +its own TaskManager instance which users can configure with dispatchers +through either the PxSceneDesc or directly through the TaskManager interface.</p> +</div> +<div class="section" id="cpudispatcher"> +<h3>CpuDispatcher<a class="headerlink" href="#cpudispatcher" title="Permalink to this headline">¶</a></h3> +<p>The CpuDispatcher is an abstract class the SDK uses for interfacing with the +application's thread pool. Typically, there will be one single +CpuDispatcher for the entire application, since there is rarely a need +for more than one thread pool. A CpuDispatcher instance may be shared by +more than one TaskManager, for example if multiple scenes are being used.</p> +<p>PhysX includes a default CpuDispatcher implementation, but we prefer +applications to implement this class themselves so PhysX and APEX can +efficiently share CPU resources with the application.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The TaskManager will call CpuDispatcher::submitTask() from either the +context of API calls (aka: scene::simulate()) or from other running +tasks, so the function must be thread-safe.</p> +</div> +<p>An implementation of the CpuDispatcher interface must call the following two methods on each submitted task for it to be run correctly:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">baseTask</span><span class="o">-></span><span class="n">run</span><span class="p">();</span> <span class="c1">// optionally call runProfiled() to wrap with PVD profiling events</span> +<span class="n">baseTask</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +<p>The PxExtensions library has default implementations for all dispatcher types, the following code snippets are taken from SampleParticles and SampleBase and show how the default dispatchers are created. +<em>mNbThreads</em> which is passed to <em>PxDefaultCpuDispatcherCreate</em> defines how many worker threads the CPU dispatcher will have.:</p> +<div class="highlight-c++"><div class="highlight"><pre> <span class="n">PxSceneDesc</span> <span class="nf">sceneDesc</span><span class="p">(</span><span class="n">mPhysics</span><span class="o">-></span><span class="n">getTolerancesScale</span><span class="p">());</span> + <span class="p">[...]</span> + <span class="c1">// create CPU dispatcher which mNbThreads worker threads</span> + <span class="n">mCpuDispatcher</span> <span class="o">=</span> <span class="n">PxDefaultCpuDispatcherCreate</span><span class="p">(</span><span class="n">mNbThreads</span><span class="p">);</span> + <span class="k">if</span><span class="p">(</span><span class="o">!</span><span class="n">mCpuDispatcher</span><span class="p">)</span> + <span class="n">fatalError</span><span class="p">(</span><span class="s">"PxDefaultCpuDispatcherCreate failed!"</span><span class="p">);</span> + <span class="n">sceneDesc</span><span class="p">.</span><span class="n">cpuDispatcher</span> <span class="o">=</span> <span class="n">mCpuDispatcher</span><span class="p">;</span> +<span class="cp">#if PX_WINDOWS</span> + <span class="c1">// create GPU dispatcher</span> + <span class="n">PxCudaContextManagerDesc</span> <span class="n">cudaContextManagerDesc</span><span class="p">;</span> + <span class="n">mCudaContextManager</span> <span class="o">=</span> <span class="n">PxCreateCudaContextManager</span><span class="p">(</span><span class="n">cudaContextManagerDesc</span><span class="p">);</span> + <span class="n">sceneDesc</span><span class="p">.</span><span class="n">gpuDispatcher</span> <span class="o">=</span> <span class="n">mCudaContextManager</span><span class="o">-></span><span class="n">getGpuDispatcher</span><span class="p">();</span> +<span class="cp">#endif</span> + <span class="p">[...]</span> + <span class="n">mScene</span> <span class="o">=</span> <span class="n">mPhysics</span><span class="o">-></span><span class="n">createScene</span><span class="p">(</span><span class="n">sceneDesc</span><span class="p">);</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Best performance is usually achieved if the number of threads is less than or equal to the available hardware threads of the platform you are running on, +creating more worker threads than hardware threads will often lead to worse performance. For platforms with a single execution core, the CPU dispatcher +can be created with zero worker threads (PxDefaultCpuDispatcherCreate(0)). In this case all work will be executed on the thread that calls PxScene::simulate(), +which can be more efficient than using multiple threads.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">CudaContextManagerDesc support appGUID now. It only works on release build. If your application employs PhysX modules that use CUDA you need to use a GUID so that patches for +new architectures can be released for your game. You can obtain a GUID for your application from NVIDIA. The application should log the failure into a file which can be +sent to NVIDIA for support.</p> +</div> +</div> +<div class="section" id="cpudispatcher-implementation-guidelines"> +<h3>CpuDispatcher Implementation Guidelines<a class="headerlink" href="#cpudispatcher-implementation-guidelines" title="Permalink to this headline">¶</a></h3> +<p>After the scene's TaskManager has found a ready-to-run task and submitted it to the +appropriate dispatcher it is up to the dispatcher implementation to decide how and +when the task will be run.</p> +<p>Often in game scenarios the rigid body simulation is time critical and the goal is to +reduce the latency from simulate() to the completion of fetchResults(). The lowest +possible latency will be achieved when the PhysX tasks have exclusive access to CPU resources +during the update. In reality, PhysX will have to share compute resources with other game tasks. +Below are some guidelines to help ensure a balance between throughput and latency when mixing +the PhysX update with other work.</p> +<ul class="simple"> +<li>Avoid interleaving long running tasks with PhysX tasks, this will help reduce latency.</li> +<li>Avoid assigning worker threads to the same execution core as higher priority threads. If a PhysX task is context switched during execution the rest of the rigid body pipeline may be stalled, increasing latency.</li> +<li>PhysX occasionally submits tasks and then immediately waits for them to complete, because of this, executing tasks in LIFO (stack) order may perform better than FIFO (queue) order.</li> +<li>PhysX is not a perfectly parallel SDK, so interleaving small to medium granularity tasks will generally result in higher overall throughput.</li> +<li>If your thread pool has per-thread job-queues then queuing tasks on the thread they were submitted may result in more optimal CPU cache coherence, however this is not required.</li> +</ul> +<p>For more details see the default CpuDispatcher implementation that comes as part of the +PxExtensions package. It uses worker threads that each have their own task queue and steal +tasks from the back of other worker's queues (LIFO order) to improve workload distribution.</p> +</div> +<div class="section" id="basetask"> +<h3>BaseTask<a class="headerlink" href="#basetask" title="Permalink to this headline">¶</a></h3> +<p>BaseTask is the abstract base class for all task types. All task +run() functions will be executed on application threads, so they +need to be careful with their stack usage, use a little stack as +possible, and they should never block for any reason.</p> +</div> +<div class="section" id="task"> +<h3>Task<a class="headerlink" href="#task" title="Permalink to this headline">¶</a></h3> +<p>The Task class is the standard task type. Tasks must be submitted to the +TaskManager each simulation step for them to be executed. Tasks may be +named at submission time, this allows them to be discoverable. Tasks +will be given a reference count of 1 when they are submitted, and the +TaskManager::startSimulation() function decrements the reference count +of all tasks and dispatches all Tasks whose reference count reaches zero. +Before TaskManager::startSimulation() is called, Tasks can set +dependencies on each other to control the order in which they are dispatched. +Once simulation has started, it is still possible to submit new tasks and +add dependencies, but it is up to the programmer to avoid race hazards. +You cannot add dependencies to tasks that have already been dispatched, +and newly submitted Tasks must have their reference count decremented +before that Task will be allowed to execute.</p> +<p>Synchronization points can also be defined using Task names. The +TaskManager will assign the name a TaskID with no Task implementation. +When all of the named TaskID's dependencies are met, it will decrement +the reference count of all Tasks with that name.</p> +<p>APEX uses the Task class almost exclusively to manage CPU +resources. The ApexScene defines a number of named Tasks that the +modules use to schedule their own Tasks (ex: start after LOD +calculations are complete, finish before the PhysX scene is stepped).</p> +</div> +<div class="section" id="lightcputask"> +<h3>LightCpuTask<a class="headerlink" href="#lightcputask" title="Permalink to this headline">¶</a></h3> +<p>LightCpuTask is another subclass of BaseTask that is explicitly +scheduled by the programmer. LightCpuTasks have a reference count of 1 +when they are initialized, so their reference count must be decremented +before they are dispatched. LightCpuTasks increment their continuation +task reference count when they are initialized, and decrement the +reference count when they are released (after completing their run() function)</p> +<p>PhysX 3.x uses LightCpuTasks almost exclusively to manage CPU +resources. For example, each stage of the simulation update may consist +of multiple parallel tasks, when each of these tasks has finished execution +it will decrement the reference count on the next task in the update chain. +This will then be automatically dispatched for execution when its reference +count reaches zero.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Even when using LightCpuTasks exclusively to manage CPU resources, the +TaskManager startSimulation() and stopSimulation() calls must be made +each simulation step to keep the GpuDispatcher synchronized.</p> +</div> +<p>The following code snippets show how the crabs' A.I. in SampleSubmarine is run as a CPU Task. By doing so the Crab A.I. is run as a background Task in parallel with the PhysX simulation update.</p> +<p>For a CPU task that does not need handling of multiple continuations <em>LightCpuTask</em> can be subclassed. A <em>LightCpuTask</em> subclass requires that the getName and a run method be defined:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Crab</span><span class="o">:</span> <span class="k">public</span> <span class="n">ClassType</span><span class="p">,</span> <span class="k">public</span> <span class="n">physx</span><span class="o">::</span><span class="n">PxLightCpuTask</span><span class="p">,</span> <span class="k">public</span> <span class="n">SampleAllocateable</span> +<span class="p">{</span> +<span class="nl">public:</span> + <span class="n">Crab</span><span class="p">(</span><span class="n">SampleSubmarine</span><span class="o">&</span> <span class="n">sample</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">crabPos</span><span class="p">,</span> <span class="n">RenderMaterial</span><span class="o">*</span> <span class="n">material</span><span class="p">);</span> + <span class="o">~</span><span class="n">Crab</span><span class="p">();</span> + <span class="p">[...]</span> + + <span class="c1">// Implements LightCpuTask</span> + <span class="k">virtual</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">getName</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="s">"Crab AI Task"</span><span class="p">;</span> <span class="p">}</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">run</span><span class="p">();</span> + + <span class="p">[...]</span> +<span class="p">}</span> +</pre></div> +</div> +<p>After PxScene::simulate() has been called, and the simulation started, the application calls removeReference() on each Crab task, this in turn causes it to be submitted to the CpuDispatcher for update. Note that it is also possible to submit tasks to the dispatcher directly (without manipulating reference counts) as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxLightCpuTask</span><span class="o">&</span> <span class="n">task</span> <span class="o">=</span> <span class="o">&</span><span class="n">mCrab</span><span class="p">;</span> +<span class="n">mCpuDispatcher</span><span class="o">-></span><span class="n">submitTask</span><span class="p">(</span><span class="n">task</span><span class="p">);</span> +</pre></div> +</div> +<p>Once queued for execution by the CpuDispatcher, one of the thread pool's worker threads will eventually call the task's run method. In this example the Crab task will perform raycasts against the scene and update its internal state machine:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">Crab</span><span class="o">::</span><span class="n">run</span><span class="p">()</span> +<span class="p">{</span> + <span class="c1">// run as a separate task/thread</span> + <span class="n">scanForObstacles</span><span class="p">();</span> + <span class="n">updateState</span><span class="p">();</span> +<span class="p">}</span> +</pre></div> +</div> +<p>It is safe to perform API read calls, such as scene queries, from multiple threads while simulate() is running. However, care must be taken not to overlap API read and write calls from multiple threads. In this case the SDK will issue an error, see <a class="reference internal" href="#threading"><em>Threading</em></a> for more information.</p> +<p>An example for explicit reference count modification and task dependency setup:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// assume all tasks have a refcount of 1 and are submitted to the task manager</span> +<span class="c1">// 3 task chains a0-a2, b0-b2, c0-c2</span> +<span class="c1">// b0 shall start after a1</span> +<span class="c1">// the a and c chain have no dependencies and shall run in parallel</span> +<span class="c1">//</span> +<span class="c1">// a0-a1-a2</span> +<span class="c1">// \</span> +<span class="c1">// b0-b1-b2</span> +<span class="c1">// c0-c1-c2</span> + +<span class="c1">// setup the 3 chains</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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="p">{</span> + <span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">setContinuation</span><span class="p">(</span><span class="o">&</span><span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">]);</span> + <span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">setContinuation</span><span class="p">(</span><span class="o">&</span><span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">]);</span> + <span class="n">c</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">setContinuation</span><span class="p">(</span><span class="o">&</span><span class="n">c</span><span class="p">[</span><span class="n">i</span><span class="o">+</span><span class="mi">1</span><span class="p">]);</span> +<span class="p">}</span> + +<span class="c1">// b0 shall start after a1</span> +<span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">startAfter</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">getTaskID</span><span class="p">());</span> + +<span class="c1">// setup is done, now start all task by decrementing their refcount by 1</span> +<span class="c1">// tasks with refcount == 0 will be submitted to the dispatcher (a0 & c0 will start).</span> +<span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">3</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">a</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">removeReference</span><span class="p">();</span> + <span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">removeReference</span><span class="p">();</span> + <span class="n">c</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">removeReference</span><span class="p">();</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Threading</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#data-access-from-multiple-threads">Data Access from Multiple Threads</a><ul> +<li><a class="reference internal" href="#scene-locking">Scene Locking</a></li> +<li><a class="reference internal" href="#locking-semantics">Locking Semantics</a></li> +<li><a class="reference internal" href="#locking-best-practices">Locking Best Practices</a></li> +</ul> +</li> +<li><a class="reference internal" href="#asynchronous-simulation">Asynchronous Simulation</a><ul> +<li><a class="reference internal" href="#double-buffering">Double Buffering</a></li> +<li><a class="reference internal" href="#events-involving-removed-objects">Events involving removed objects</a></li> +<li><a class="reference internal" href="#support">Support</a></li> +<li><a class="reference internal" href="#memory-considerations">Memory Considerations</a></li> +</ul> +</li> +<li><a class="reference internal" href="#multithreaded-simulation">Multithreaded Simulation</a><ul> +<li><a class="reference internal" href="#taskmanager">TaskManager</a></li> +<li><a class="reference internal" href="#cpudispatcher">CpuDispatcher</a></li> +<li><a class="reference internal" href="#cpudispatcher-implementation-guidelines">CpuDispatcher Implementation Guidelines</a></li> +<li><a class="reference internal" href="#basetask">BaseTask</a></li> +<li><a class="reference internal" href="#task">Task</a></li> +<li><a class="reference internal" href="#lightcputask">LightCpuTask</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="Startup.html" + title="previous chapter">Startup and Shutdown</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Geometry.html" + title="next chapter">Geometry</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" /> + <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="Geometry.html" title="Geometry" + >next</a></li> + <li class="right" > + <a href="Startup.html" title="Startup and Shutdown" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/Vehicles.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/Vehicles.html new file mode 100644 index 00000000..4abb5ee7 --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/Vehicles.html @@ -0,0 +1,1942 @@ +<!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>Vehicles — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Character Controllers" href="CharacterControllers.html" /> + <link rel="prev" title="Scene Queries" href="SceneQueries.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="CharacterControllers.html" title="Character Controllers" + accesskey="N">next</a></li> + <li class="right" > + <a href="SceneQueries.html" title="Scene Queries" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="vehicles"> +<span id="id1"></span><h1>Vehicles<a class="headerlink" href="#vehicles" title="Permalink to this headline">¶</a></h1> +<div class="section" id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>PhysX support for vehicles has been significantly reworked in 3.x. In place of the NxWheelShape class of 2.8.x, a more optimal integration of the core PhysX SDK and vehicle simulation code has been developed. More specifically, the vehicles component now sits outside the core SDK in a manner similar to PhysXExtensions. This change allows vehicles to be updated in a single pass as well as promoting a more intuitive approach to modeling vehicle data. Vehicles support has been extended from the suspension/wheel/tire modeling of 2.8.x to a more complete model that couples modular vehicle components including engine, clutch, gears, autobox, differential, wheels, tires, suspensions, and chassis. A quick glance at the data structures in PxVehicleComponents.h will provide a flavor of the behaviors supported by PhysX vehicles.</p> +</div> +<div class="section" id="algorithm"> +<span id="id2"></span><h2>Algorithm<a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h2> +<p>The PhysX Vehicle SDK models vehicles as collections of sprung masses, where each sprung mass represents a suspension line with associated wheel and tire data. These collections of sprung masses have a complementary representation as a rigid body actor whose mass, center of mass, and moment of inertia matches exactly the masses and coordinates of the sprung masses. This is illustrated below.</p> +<div class="figure align-center" id="figure-1a"> +<a class="reference internal image-reference" href="../_images/CarRigidBody.png"><img alt="../_images/CarRigidBody.png" src="../_images/CarRigidBody.png" /></a> +<p class="caption">Figure 1a: Vehicle representation as a rigid body actor with shapes for the chassis and wheels. Note that the wheel rest offsets are specified relative to the center of mass.</p> +</div> +<div class="figure align-center" id="figure-1b"> +<a class="reference internal image-reference" href="../_images/CarSprungMass.png"><img alt="../_images/CarSprungMass.png" src="../_images/CarSprungMass.png" /></a> +<p class="caption">Figure 1b: Vehicle representation as a collection of sprung masses of mass M1 and M2.</p> +</div> +<p>The relationship between the sprung mass and rigid body vehicle representations can be mathematically formalized with the rigid body center of mass equations:</p> +<blockquote> +<div><p>M = M1 + M2</p> +<p>Xcm = (M1 x X1 + M2 x X2)/(M1 + M2)</p> +</div></blockquote> +<p>where M1 and M2 are the sprung masses; X1 and X2 are the sprung mass coordinates in actor space; M is the rigid body mass; and Xcm is the rigid body center of mass offset.</p> +<p>The purpose of the PhysX Vehicle SDK update function is to compute suspension and tire forces using the sprung mass model and then to apply the aggregate of these forces to the PhysX SDK rigid body representation in the form of a modified velocity and angular velocity. Interaction of the rigid body actor with other scene objects and global pose update is then managed by the PhysX SDK.</p> +<p>The update of each vehicle begins with a raycast for each suspension line. The raycast starts just above the the top of the tire at maximum compression and casts downwards along the direction of suspension travel to a position just below the bottom of the tire at maximum droop. This is shown in the diagram below.</p> +<div class="figure align-center" id="figure-2"> +<a class="reference internal image-reference" href="../_images/CarRaycast.png"><img alt="../_images/CarRaycast.png" src="../_images/CarRaycast.png" /></a> +<p class="caption">Figure 2: Suspension limits and suspension raycasts.</p> +</div> +<p>The suspension force from each elongated or compressed spring is computed and added to the aggregate force to be applied to the rigid body. Additionally, the suspension force is used to compute the load that is bearing down on the tire. This load is used to determine the tire forces that will be generated in the contact plane and then added to the aggregate force to be applied to the rigid body. The tire force computation actually depends on a number of factors including steer angle, camber angle, friction, wheel rotation speed, and rigid body momentum. The aggregated force of all tire and suspension forces is then applied to the rigid body actor associated with the vehicle so that the transform may be modified accordingly in the next PhysX SDK update.</p> +<p>In addition to being collections of sprung masses, PhysX vehicles also support a variety of drive models. The center of the drive model is a torsion clutch, which couples together the wheels and the engine via forces that arise from differences in rotational speeds at both sides of the clutch. At one side of the clutch is the engine, which is powered directly from the accelerator pedal. The engine is modeled as a rigid body whose motion is purely rotational and limited to a single degree of rotational freedom. At the other side of the clutch are the gearing system, the differential and the wheels. The effective rotational speed of the other side of the clutch can be computed directly from the gearing ratio and the rotational speed of the wheels that are coupled to the clutch through the differential. This model naturally allows engine torques to propagate to the wheels and wheel torques to propagate back to the engine, just as in a standard car.</p> +<p>The data describing each component of the PhysX vehicle can be found in Section <a class="reference internal" href="#tuning-guide"><em>Tuning Guide</em></a>.</p> +</div> +<div class="section" id="first-code"> +<h2>First Code<a class="headerlink" href="#first-code" title="Permalink to this headline">¶</a></h2> +<div class="section" id="vehicle-sdk-initialization"> +<h3>Vehicle SDK Initialization<a class="headerlink" href="#vehicle-sdk-initialization" title="Permalink to this headline">¶</a></h3> +<p>Before using the vehicle SDK it must first be initialized in order to set up a number of threshold values from various tolerance scales. This is as straightforward as calling the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="kt">bool</span> <span class="n">PX_CALL_CONV</span> <span class="nf">PxInitVehicleSDK</span> + <span class="p">(</span><span class="n">PxPhysics</span><span class="o">&</span> <span class="n">physics</span><span class="p">,</span> <span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">serializationRegistry</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">);</span> +</pre></div> +</div> +<p>This function should be called after setting up the required PxPhysics and PxFoundation instances. If vehicle serialization is required a PxSerializationRegistry instance needs to be specified. A PxSerializationRegistry instance can be created with PxSerialization::createSerializationRegistry(), see <a class="reference internal" href="Serialization.html#serialization"><em>Serialization</em></a>.</p> +<p>The basis vectors of the vehicle simulation must also be configured so that longitudinal and lateral tire slips may be unambiguously computed:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">PxVehicleSetBasisVectors</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">up</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">forward</span><span class="p">);</span> +</pre></div> +</div> +<p>This function can be called at any time prior to the first execution of PxVehicleUpdates.</p> +<p>The rigid body actors associated with vehicles can be updated either immediately with velocity modifications or updated with an acceleration that is applied in the next PhysX SDK simulate call. The following function can be used to select the required update mode:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">PxVehicleSetUpdateMode</span><span class="p">(</span><span class="n">PxVehicleUpdateMode</span><span class="o">::</span><span class="n">Enum</span> <span class="n">vehicleUpdateMode</span><span class="p">);</span> +</pre></div> +</div> +<p>As expected, the vehicle SDK also has a shutdown process which needs to be invoked:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_C_EXPORT</span> <span class="kt">void</span> <span class="n">PX_CALL_CONV</span> <span class="nf">PxCloseVehicleSDK</span> + <span class="p">(</span><span class="n">PxSerializationRegistry</span><span class="o">*</span> <span class="n">serializationRegistry</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">);</span> +</pre></div> +</div> +<p>This needs to be called before the PxPhysics instance and PxFoundation instance are released; that is, the order of shutdown is the reverse of the initialization order. In addition if serialization is required the PxSerializationRegistry specified for PxInitVehicleSDK needs to be passed to PxCloseVehicleSDK. If vehicle serialization is used then this must be called before closing the PhysXExtensions.</p> +<p>As an illustration of the usage of these functions, SnippetVehicle4W has the following initialization code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxInitVehicleSDK</span><span class="p">(</span><span class="o">*</span><span class="n">gPhysics</span><span class="p">);</span> +<span class="n">PxVehicleSetBasisVectors</span><span class="p">(</span><span class="n">PxVec3</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="n">PxVec3</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="mi">1</span><span class="p">));</span> +<span class="n">PxVehicleSetUpdateMode</span><span class="p">(</span><span class="n">PxVehicleUpdateMode</span><span class="o">::</span><span class="n">eVELOCITY_CHANGE</span><span class="p">);</span> +</pre></div> +</div> +<p>The shutdown code in SnippetVehicle4W is as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxCloseVehicleSDK</span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="introduction-to-vehicle-creation"> +<span id="id3"></span><h3>Introduction To Vehicle Creation<a class="headerlink" href="#introduction-to-vehicle-creation" title="Permalink to this headline">¶</a></h3> +<p>The following pseudo-code illustrates the basic process of setting up a PxVehicleDrive4W instance:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">const</span> <span class="n">PxU32</span> <span class="n">numWheels</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span> + +<span class="n">PxVehicleWheelsSimData</span><span class="o">*</span> <span class="n">wheelsSimData</span> <span class="o">=</span> <span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="n">numWheels</span><span class="p">);</span> +<span class="n">setupWheelsSimulationData</span><span class="p">(</span><span class="n">wheelsSimData</span><span class="p">);</span> + +<span class="n">PxVehicleDriveSimData4W</span> <span class="n">driveSimData</span><span class="p">;</span> +<span class="n">setupDriveSimData</span><span class="p">(</span><span class="n">driveSimData</span><span class="p">);</span> + +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">vehActor</span> <span class="o">=</span> <span class="n">myPhysics</span><span class="p">.</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">startPose</span><span class="p">);</span> +<span class="n">setupVehicleActor</span><span class="p">(</span><span class="n">vehActor</span><span class="p">);</span> +<span class="n">myScene</span><span class="p">.</span><span class="n">addActor</span><span class="p">(</span><span class="o">*</span><span class="n">vehActor</span><span class="p">);</span> + +<span class="n">PxVehicleDrive4W</span><span class="o">*</span> <span class="n">vehDrive4W</span> <span class="o">=</span> <span class="n">PxVehicleDrive4W</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="n">numWheels</span><span class="p">);</span> +<span class="n">vehDrive4W</span><span class="o">-></span><span class="n">setup</span><span class="p">(</span><span class="n">physics</span><span class="p">,</span> <span class="n">veh4WActor</span><span class="p">,</span> <span class="o">*</span><span class="n">wheelsSimData</span><span class="p">,</span> <span class="n">driveSimData</span><span class="p">,</span> <span class="n">numWheels</span> <span class="o">-</span> <span class="mi">4</span><span class="p">);</span> +<span class="n">wheelsSimData</span><span class="o">-></span><span class="n">free</span><span class="p">();</span> +</pre></div> +</div> +<p>The code above first instantiates a PxVehicleWheelsSimData instance with internal buffers that are large enough to store configuration data for four wheels. This configuration data includes fields such as suspension strength and damping rate, wheel mass, tire stiffness and suspension travel direction. The next step is to create a PxVehicleDriveSimData4W instance. This structure stores the configuration of the drive model and includes data fields such as engine peak torque, clutch strength, gearing ratios, and Ackermann steering correction. Following this, a PxRigidDynamicActor is instantiated and configured with geometry for the wheels and chassis as well as dynamic properties such as mass, moment of inertia, and center of mass. The final step is to instantiate a PxVehicleDrive4W instance and associate it with the actor and the vehicle configuration data.</p> +<p>The functions setupWheelsSimulationData, setupDriveSimData and setupVehicleActor are actually quite involved and shall be discussed in future Sections <a class="reference internal" href="#setupwheelssimulationdata"><em>setupWheelsSimulationData</em></a>, <a class="reference internal" href="#setupdrivesimdata"><em>setupDriveSimData</em></a> and <a class="reference internal" href="#setupvehicleactor"><em>setupVehicleActor</em></a>.</p> +</div> +<div class="section" id="introduction-to-vehicle-update"> +<span id="id4"></span><h3>Introduction To Vehicle Update<a class="headerlink" href="#introduction-to-vehicle-update" title="Permalink to this headline">¶</a></h3> +<p>The PhysX Vehicles SDK utilizes batched scene queries to query the geometry under each tire. A more detailed discussion of PhysX batched scene queries can be found in Section <a class="reference internal" href="SceneQueries.html#batched-queries"><em>Batched queries</em></a>.</p> +<p>The following pseudo-code initializes a batched scene query with buffers large enough for a single vehicle with four wheels:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRaycastQueryResult</span> <span class="n">sqResults</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span> +<span class="n">PxRaycastHit</span> <span class="n">sqHitBuffer</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span> +<span class="n">PxBatchQueryDesc</span> <span class="nf">sqDesc</span><span class="p">(</span><span class="mi">4</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="n">sqDesc</span><span class="p">.</span><span class="n">queryMemory</span><span class="p">.</span><span class="n">userRaycastResultBuffer</span> <span class="o">=</span> <span class="n">sqResults</span><span class="p">;</span> +<span class="n">sqDesc</span><span class="p">.</span><span class="n">queryMemory</span><span class="p">.</span><span class="n">userRaycastTouchBuffer</span> <span class="o">=</span> <span class="n">sqHitBuffer</span><span class="p">;</span> +<span class="n">sqDesc</span><span class="p">.</span><span class="n">queryMemory</span><span class="p">.</span><span class="n">raycastTouchBufferSize</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span> +<span class="n">sqDesc</span><span class="p">.</span><span class="n">preFilterShader</span> <span class="o">=</span> <span class="n">myFilterShader</span><span class="p">;</span> +<span class="n">PxBatchQuery</span><span class="o">*</span> <span class="n">batchQuery</span> <span class="o">=</span> <span class="n">scene</span><span class="o">-></span><span class="n">createBatchQuery</span><span class="p">(</span><span class="n">sqDesc</span><span class="p">);</span> +</pre></div> +</div> +<p>The PxBatchQuery instance is typically instantiated as part of the initialization phase and then reused each frame. It is possible to instantiate a PxBatchQuery instance for each vehicle or to instantiate a single PxBatchQuery instance with buffers large enough for all wheels of a batched array of vehicles. The only restriction is that all batched vehicle arrays and associated buffers configured at the start of a vehicle simulation frame must persist until the end of the vehicle simulation frame.</p> +<p>PhysX vehicles make use of scene query filter shaders to eliminate intersections with the vehicle issuing the raycast and with any geometry that is not to be considered as a drivable surface. More details for how to set up "myFilterShader" above can be found in Section <a class="reference internal" href="#filtering"><em>Filtering</em></a>.</p> +<p>For a batch containing just a single 4-wheeled vehicle the suspension raycasts can be performed with the following pseudo-code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleWheels</span><span class="o">*</span> <span class="n">vehicles</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="n">myVehicle</span><span class="p">};</span> +<span class="n">PxVehicleSuspensionRaycasts</span><span class="p">(</span><span class="n">batchQuery</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">vehicles</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="n">sqResults</span><span class="p">);</span> +</pre></div> +</div> +<p>The function PxVehicleSuspensionRaycasts performs suspension raycasts for all vehicles in the batched array of vehicles. Each element in the sqResults array corresponds to the raycast report for a single suspension. Pointers to contiguous blocks within sqResults are stored by each vehicle in turn as the function iterates through the vehicles array. These memory blocks are stored by each vehicle so that they may easily query the suspension raycast results in PxVehicleUpdates. As a consequence, the sqResults array must persist until at least the end of PxVehicleUpdates and must have length at least as large as the total number of wheels in the vehicles array.</p> +<p>The vehicles are updated with the following function call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleUpdates</span><span class="p">(</span><span class="n">timestep</span><span class="p">,</span> <span class="n">gravity</span><span class="p">,</span> <span class="n">frictionPairs</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">vehicles</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> +</pre></div> +</div> +<p>The function PxVehicleUpdates updates the internal dynamics of each vehicle, poses the wheel shapes of the vehicle's actor and applies either velocity or acceleration changes to the actor, depending on the update mode chosen with PxVehicleSetUpdateMode. More details can be found in Section <a class="reference internal" href="#wheel-pose"><em>Wheel Pose</em></a> and Section <a class="reference internal" href="#vehicle-update"><em>Vehicle Update</em></a>. The parameter frictionPairs is basically a lookup table that associates unique friction values with combinations of tire type and PxMaterial. The idea here is to allow tire response to be tuned for each surface type. This shall be discussed in more depth in Section <a class="reference internal" href="#tire-friction-on-drivable-surfaces"><em>Tire Friction on Drivable Surfaces</em></a>.</p> +</div> +</div> +<div class="section" id="snippets"> +<h2>Snippets<a class="headerlink" href="#snippets" title="Permalink to this headline">¶</a></h2> +<p>Four snippets are currently implemented to illustrate the operation of the PhysX Vehicles SDK. These are:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="mf">1.</span> <span class="n">SnippetVehicle4W</span> +<span class="mf">2.</span> <span class="n">SnippetVehicleTank</span> + <span class="mf">3.</span> <span class="n">SnippetNoDrive</span> +<span class="mf">3.</span> <span class="n">SnippetVehicleScale</span> +<span class="mf">4.</span> <span class="n">SnippetVehicleMultiThreading</span> + <span class="mf">5.</span> <span class="n">SnippetVehicleWheelContactMod</span> +</pre></div> +</div> +<p>Code snippets from each of these is used throughout the guide.</p> +<div class="section" id="snippetvehicle4w"> +<h3>SnippetVehicle4W<a class="headerlink" href="#snippetvehicle4w" title="Permalink to this headline">¶</a></h3> +<p>SnippetVehicle4W demonstrates how to instantiate and update vehicles of type PxVehicleDrive4W. It creates a vehicle on a plane and then controls the vehicle so that it performs a number of choreographed maneuvers such as accelerate, reverse, brake, handbrake, and turn.</p> +</div> +<div class="section" id="snippetvehicletank"> +<h3>SnippetVehicleTank<a class="headerlink" href="#snippetvehicletank" title="Permalink to this headline">¶</a></h3> +<p>SnippetVehicleTank demonstrates how to instantiate and update vehicles of type PxVehicleDriveTank. It creates a tank on a plane and then controls the tank so that it performs a number of choreographed maneuvers such as accelerate, reverse, soft turns, and hard turns.</p> +</div> +<div class="section" id="snippetvehiclenodrive"> +<h3>SnippetVehicleNoDrive<a class="headerlink" href="#snippetvehiclenodrive" title="Permalink to this headline">¶</a></h3> +<p>SnippetVehicleNoDrive demonstrates how to instantiate and update vehicles of type PxVehicleNoDrive. It creates a vehicle on a plane and then controls the vehicle so that it performs a number of choreographed manoeuvres such as accelerate, reverse, soft turns, and hard turns.</p> +</div> +<div class="section" id="snippetvehiclescale"> +<h3>SnippetVehicleScale<a class="headerlink" href="#snippetvehiclescale" title="Permalink to this headline">¶</a></h3> +<p>SnippetVehicleScale demonstrates how to configure a PhysX vehicle when meters are not the chosen length scale. The snippet sets up a vehicle with meters as the adopted length scale and then modifies the vehicle parameters so that they represent the same vehicle but with centimeters as the chosen length scale.</p> +</div> +<div class="section" id="snippetvehiclemultithreading"> +<h3>SnippetVehicleMultiThreading<a class="headerlink" href="#snippetvehiclemultithreading" title="Permalink to this headline">¶</a></h3> +<p>SnippetVehicleMultiThreading demonstrates how to implement multi-threaded vehicles. It creates multiple vehicles on a plane and then concurrently simulates them in parallel across multiple threads.</p> +</div> +</div> +<div class="section" id="advanced-concepts"> +<h2>Advanced Concepts<a class="headerlink" href="#advanced-concepts" title="Permalink to this headline">¶</a></h2> +<div class="section" id="vehicle-creation"> +<h3>Vehicle Creation<a class="headerlink" href="#vehicle-creation" title="Permalink to this headline">¶</a></h3> +<p>This Section discusses the configuration of vehicle simulation data and describes how to set up an actor that will represent the vehicle in the PhysX SDK. Section <a class="reference internal" href="#introduction-to-vehicle-creation"><em>Introduction To Vehicle Creation</em></a> identified three distinct phases of vehicle configuration: configuration of wheel simulation data, configuration of drive simulation data and actor configuration. Each of these phases is discussed in turn.</p> +<div class="section" id="setupwheelssimulationdata"> +<span id="id5"></span><h4>setupWheelsSimulationData<a class="headerlink" href="#setupwheelssimulationdata" title="Permalink to this headline">¶</a></h4> +<p>The following code, taken from SnippetVehicle4W, instantiates a PxVehicleWheelsSimData:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">setupWheelsSimulationData</span><span class="p">(</span><span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelMass</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelMOI</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelRadius</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelWidth</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">numWheels</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">wheelCenterActorOffsets</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">chassisCMOffset</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">chassisMass</span><span class="p">,</span> <span class="n">PxVehicleWheelsSimData</span><span class="o">*</span> <span class="n">wheelsSimData</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//Set up the wheels.</span> + <span class="n">PxVehicleWheelData</span> <span class="n">wheels</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="p">{</span> + <span class="c1">//Set up the wheel data structures with mass, moi, radius, width.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">wheels</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mMass</span> <span class="o">=</span> <span class="n">wheelMass</span><span class="p">;</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mMOI</span> <span class="o">=</span> <span class="n">wheelMOI</span><span class="p">;</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mRadius</span> <span class="o">=</span> <span class="n">wheelRadius</span><span class="p">;</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mWidth</span> <span class="o">=</span> <span class="n">wheelWidth</span><span class="p">;</span> + <span class="p">}</span> + + <span class="c1">//Enable the handbrake for the rear wheels only.</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_LEFT</span><span class="p">].</span><span class="n">mMaxHandBrakeTorque</span><span class="o">=</span><span class="mf">4000.0f</span><span class="p">;</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_RIGHT</span><span class="p">].</span><span class="n">mMaxHandBrakeTorque</span><span class="o">=</span><span class="mf">4000.0f</span><span class="p">;</span> + <span class="c1">//Enable steering for the front wheels only.</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_LEFT</span><span class="p">].</span><span class="n">mMaxSteer</span><span class="o">=</span><span class="n">PxPi</span><span class="o">*</span><span class="mf">0.3333f</span><span class="p">;</span> + <span class="n">wheels</span><span class="p">[</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_RIGHT</span><span class="p">].</span><span class="n">mMaxSteer</span><span class="o">=</span><span class="n">PxPi</span><span class="o">*</span><span class="mf">0.3333f</span><span class="p">;</span> + <span class="p">}</span> + + <span class="c1">//Set up the tires.</span> + <span class="n">PxVehicleTireData</span> <span class="n">tires</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="p">{</span> + <span class="c1">//Set up the tires.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">tires</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mType</span> <span class="o">=</span> <span class="n">TIRE_TYPE_NORMAL</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> + + <span class="c1">//Set up the suspensions</span> + <span class="n">PxVehicleSuspensionData</span> <span class="n">suspensions</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="p">{</span> + <span class="c1">//Compute the mass supported by each suspension spring.</span> + <span class="n">PxF32</span> <span class="n">suspSprungMasses</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="n">PxVehicleComputeSprungMasses</span> + <span class="p">(</span><span class="n">numWheels</span><span class="p">,</span> <span class="n">wheelCenterActorOffsets</span><span class="p">,</span> + <span class="n">chassisCMOffset</span><span class="p">,</span> <span class="n">chassisMass</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">suspSprungMasses</span><span class="p">);</span> + + <span class="c1">//Set the suspension data.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">suspensions</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mMaxCompression</span> <span class="o">=</span> <span class="mf">0.3f</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mMaxDroop</span> <span class="o">=</span> <span class="mf">0.1f</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mSpringStrength</span> <span class="o">=</span> <span class="mf">35000.0f</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mSpringDamperRate</span> <span class="o">=</span> <span class="mf">4500.0f</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mSprungMass</span> <span class="o">=</span> <span class="n">suspSprungMasses</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> + <span class="p">}</span> + + <span class="c1">//Set the camber angles.</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">camberAngleAtRest</span><span class="o">=</span><span class="mf">0.0</span><span class="p">;</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">camberAngleAtMaxDroop</span><span class="o">=</span><span class="mf">0.01f</span><span class="p">;</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">camberAngleAtMaxCompression</span><span class="o">=-</span><span class="mf">0.01f</span><span class="p">;</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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="p">{</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">0</span><span class="p">].</span><span class="n">mCamberAtRest</span> <span class="o">=</span> <span class="n">camberAngleAtRest</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">].</span><span class="n">mCamberAtRest</span> <span class="o">=</span> <span class="o">-</span><span class="n">camberAngleAtRest</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">0</span><span class="p">].</span><span class="n">mCamberAtMaxDroop</span> <span class="o">=</span> <span class="n">camberAngleAtMaxDroop</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">].</span><span class="n">mCamberAtMaxDroop</span> <span class="o">=</span> <span class="o">-</span><span class="n">camberAngleAtMaxDroop</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">0</span><span class="p">].</span><span class="n">mCamberAtMaxCompression</span> <span class="o">=</span> <span class="n">camberAngleAtMaxCompression</span><span class="p">;</span> + <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span> <span class="o">+</span> <span class="mi">1</span><span class="p">].</span><span class="n">mCamberAtMaxCompression</span> <span class="o">=</span> <span class="o">-</span><span class="n">camberAngleAtMaxCompression</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> + + <span class="c1">//Set up the wheel geometry.</span> + <span class="n">PxVec3</span> <span class="n">suspTravelDirections</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="n">PxVec3</span> <span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="n">PxVec3</span> <span class="n">suspForceAppCMOffsets</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="n">PxVec3</span> <span class="n">tireForceAppCMOffsets</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> + <span class="p">{</span> + <span class="c1">//Set the geometry data.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">//Vertical suspension travel.</span> + <span class="n">suspTravelDirections</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">PxVec3</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">);</span> + + <span class="c1">//Wheel center offset is offset from rigid body center of mass.</span> + <span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> + <span class="n">wheelCenterActorOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">-</span> <span class="n">chassisCMOffset</span><span class="p">;</span> + + <span class="c1">//Suspension force application point 0.3 metres below</span> + <span class="c1">//rigid body center of mass.</span> + <span class="n">suspForceAppCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> + <span class="n">PxVec3</span><span class="p">(</span><span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">x</span><span class="p">,</span><span class="o">-</span><span class="mf">0.3f</span><span class="p">,</span><span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">z</span><span class="p">);</span> + + <span class="c1">//Tire force application point 0.3 metres below</span> + <span class="c1">//rigid body center of mass.</span> + <span class="n">tireForceAppCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> + <span class="n">PxVec3</span><span class="p">(</span><span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">x</span><span class="p">,</span><span class="o">-</span><span class="mf">0.3f</span><span class="p">,</span><span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">z</span><span class="p">);</span> + <span class="p">}</span> + <span class="p">}</span> + + <span class="c1">//Set up the filter data of the raycast that will be issued by each suspension.</span> + <span class="n">PxFilterData</span> <span class="n">qryFilterData</span><span class="p">;</span> + <span class="n">setupNonDrivableSurface</span><span class="p">(</span><span class="n">qryFilterData</span><span class="p">);</span> + + <span class="c1">//Set the wheel, tire and suspension data.</span> + <span class="c1">//Set the geometry data.</span> + <span class="c1">//Set the query filter data</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">wheelsSimData</span><span class="o">-></span><span class="n">setWheelData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">wheels</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setTireData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">tires</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setSuspensionData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">suspensions</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setSuspTravelDirection</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">suspTravelDirections</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setWheelCentreOffset</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">wheelCentreCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setSuspForceAppPointOffset</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">suspForceAppCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setTireForceAppPointOffset</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">tireForceAppCMOffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setSceneQueryFilterData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">qryFilterData</span><span class="p">);</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setWheelShapeMapping</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The function PxVehicleComputeSprungMasses computes the sprung mass of each suspension so that they collectively match the rigid body center of mass. This is performed in the frame of the actor. It makes sense to perform PxVehicleComputeSprungMasses in the frame of the actor because the rigid body center of mass is always specified in the actor's frame. The vehicle suspension system, on the other hand, is specified in the center of mass frame. As a consequence, the functions setWheelCentreOffset, setSuspForceAppPointOffset and setTireForceAppPointOffset all describe offsets from the rigid body center of mass. The directness of this approach can make changes to the rigid body center of mass a bit more involved than might be expected. To solve this problem the function PxVehicleUpdateCMassLocalPose has been introduced, though not used in the code above. This function recomputes and sets all suspension offsets, recomputes the sprung masses and sets them in a way that preserves the natural frequency and damping ratio of each spring.</p> +<p>Details of many of the parameters and functions above can be found in Section <a class="reference internal" href="#tuning-guide"><em>Tuning Guide</em></a>. The function setupNonDrivableSurface, which sets up scene query filter data for each suspension raycast, shall be discussed in more detail in Section <a class="reference internal" href="#filtering"><em>Filtering</em></a>. Further, the link between TIRE_TYPE_NORMAL and tire friction shall be made clear in Section <a class="reference internal" href="#tire-friction-on-drivable-surfaces"><em>Tire Friction on Drivable Surfaces</em></a>. Finally, the use of the function setWheelShapeMapping shall be clarified in Section <a class="reference internal" href="#wheel-pose"><em>Wheel Pose</em></a>.</p> +</div> +<div class="section" id="setupdrivesimdata"> +<span id="id6"></span><h4>setupDriveSimData<a class="headerlink" href="#setupdrivesimdata" title="Permalink to this headline">¶</a></h4> +<p>The following code, taken from SnippetVehicle4W, instantiates a PxVehicleDriveSimData4W:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDriveSimData4W</span> <span class="n">driveSimData</span><span class="p">;</span> +<span class="p">{</span> + <span class="c1">//Diff</span> + <span class="n">PxVehicleDifferential4WData</span> <span class="n">diff</span><span class="p">;</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mType</span><span class="o">=</span><span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_4WD</span><span class="p">;</span> + <span class="n">driveSimData</span><span class="p">.</span><span class="n">setDiffData</span><span class="p">(</span><span class="n">diff</span><span class="p">);</span> + + <span class="c1">//Engine</span> + <span class="n">PxVehicleEngineData</span> <span class="n">engine</span><span class="p">;</span> + <span class="n">engine</span><span class="p">.</span><span class="n">mPeakTorque</span><span class="o">=</span><span class="mf">500.0f</span><span class="p">;</span> + <span class="n">engine</span><span class="p">.</span><span class="n">mMaxOmega</span><span class="o">=</span><span class="mf">600.0f</span><span class="p">;</span><span class="c1">//approx 6000 rpm</span> + <span class="n">driveSimData</span><span class="p">.</span><span class="n">setEngineData</span><span class="p">(</span><span class="n">engine</span><span class="p">);</span> + + <span class="c1">//Gears</span> + <span class="n">PxVehicleGearsData</span> <span class="n">gears</span><span class="p">;</span> + <span class="n">gears</span><span class="p">.</span><span class="n">mSwitchTime</span><span class="o">=</span><span class="mf">0.5f</span><span class="p">;</span> + <span class="n">driveSimData</span><span class="p">.</span><span class="n">setGearsData</span><span class="p">(</span><span class="n">gears</span><span class="p">);</span> + + <span class="c1">//Clutch</span> + <span class="n">PxVehicleClutchData</span> <span class="n">clutch</span><span class="p">;</span> + <span class="n">clutch</span><span class="p">.</span><span class="n">mStrength</span><span class="o">=</span><span class="mf">10.0f</span><span class="p">;</span> + <span class="n">driveSimData</span><span class="p">.</span><span class="n">setClutchData</span><span class="p">(</span><span class="n">clutch</span><span class="p">);</span> + + <span class="c1">//Ackermann steer accuracy</span> + <span class="n">PxVehicleAckermannGeometryData</span> <span class="n">ackermann</span><span class="p">;</span> + <span class="n">ackermann</span><span class="p">.</span><span class="n">mAccuracy</span><span class="o">=</span><span class="mf">1.0f</span><span class="p">;</span> + <span class="n">ackermann</span><span class="p">.</span><span class="n">mAxleSeparation</span><span class="o">=</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_LEFT</span><span class="p">).</span><span class="n">z</span><span class="o">-</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_LEFT</span><span class="p">).</span><span class="n">z</span><span class="p">;</span> + <span class="n">ackermann</span><span class="p">.</span><span class="n">mFrontWidth</span><span class="o">=</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_RIGHT</span><span class="p">).</span><span class="n">x</span><span class="o">-</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_LEFT</span><span class="p">).</span><span class="n">x</span><span class="p">;</span> + <span class="n">ackermann</span><span class="p">.</span><span class="n">mRearWidth</span><span class="o">=</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_RIGHT</span><span class="p">).</span><span class="n">x</span><span class="o">-</span> + <span class="n">wheelsSimData</span><span class="o">-></span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_LEFT</span><span class="p">).</span><span class="n">x</span><span class="p">;</span> + <span class="n">driveSimData</span><span class="p">.</span><span class="n">setAckermannGeometryData</span><span class="p">(</span><span class="n">ackermann</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Details of many of the parameters and functions above can be found in Section <a class="reference internal" href="#tuning-guide"><em>Tuning Guide</em></a>.</p> +<p>Configuring PxVehicleDriveSimDataNW and PxVehicleDriveSimDataTank instances follow a very similar procedure, albeit with slightly different components. More details can be found, for example, in SnippetVehicleTank.</p> +</div> +<div class="section" id="setupvehicleactor"> +<span id="id7"></span><h4>setupVehicleActor<a class="headerlink" href="#setupvehicleactor" title="Permalink to this headline">¶</a></h4> +<p>The following code, common to all vehicle snippets, sets up a rigid dynamic actor with geometry, filter and dynamics data:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="nf">createVehicleActor</span> +<span class="p">(</span><span class="k">const</span> <span class="n">PxVehicleChassisData</span><span class="o">&</span> <span class="n">chassisData</span><span class="p">,</span> + <span class="n">PxMaterial</span><span class="o">**</span> <span class="n">wheelMaterials</span><span class="p">,</span> <span class="n">PxConvexMesh</span><span class="o">**</span> <span class="n">wheelConvexMeshes</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">numWheels</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxFilterData</span><span class="o">&</span> <span class="n">wheelSimFilterData</span><span class="p">,</span> + <span class="n">PxMaterial</span><span class="o">**</span> <span class="n">chassisMaterials</span><span class="p">,</span> <span class="n">PxConvexMesh</span><span class="o">**</span> <span class="n">chassisConvexMeshes</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">numChassisMeshes</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxFilterData</span><span class="o">&</span> <span class="n">chassisSimFilterData</span><span class="p">,</span> + <span class="n">PxPhysics</span><span class="o">&</span> <span class="n">physics</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//We need a rigid body actor for the vehicle.</span> + <span class="c1">//Don't forget to add the actor to the scene after setting up the associated vehicle.</span> + <span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">vehActor</span> <span class="o">=</span> <span class="n">physics</span><span class="p">.</span><span class="n">createRigidDynamic</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> + + <span class="c1">//Wheel and chassis query filter data.</span> + <span class="c1">//Optional: cars don't drive on other cars.</span> + <span class="n">PxFilterData</span> <span class="n">wheelQryFilterData</span><span class="p">;</span> + <span class="n">setupNonDrivableSurface</span><span class="p">(</span><span class="n">wheelQryFilterData</span><span class="p">);</span> + <span class="n">PxFilterData</span> <span class="n">chassisQryFilterData</span><span class="p">;</span> + <span class="n">setupNonDrivableSurface</span><span class="p">(</span><span class="n">chassisQryFilterData</span><span class="p">);</span> + + <span class="c1">//Add all the wheel shapes to the actor.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">PxConvexMeshGeometry</span> <span class="n">geom</span><span class="p">(</span><span class="n">wheelConvexMeshes</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">PxShape</span><span class="o">*</span> <span class="n">wheelShape</span><span class="o">=</span><span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">vehActor</span><span class="p">,</span> <span class="n">geom</span><span class="p">,</span> <span class="o">*</span><span class="n">wheelMaterials</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelShape</span><span class="o">-></span><span class="n">setQueryFilterData</span><span class="p">(</span><span class="n">wheelQryFilterData</span><span class="p">);</span> + <span class="n">wheelShape</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">wheelSimFilterData</span><span class="p">);</span> + <span class="n">wheelShape</span><span class="o">-></span><span class="n">setLocalPose</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> + <span class="p">}</span> + + <span class="c1">//Add the chassis shapes to the actor.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numChassisMeshes</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">PxShape</span><span class="o">*</span> <span class="n">chassisShape</span><span class="o">=</span><span class="n">PxRigidActorExt</span><span class="o">::</span><span class="n">createExclusiveShape</span><span class="p">(</span><span class="o">*</span><span class="n">vehActor</span><span class="p">,</span> <span class="n">PxConvexMeshGeometry</span><span class="p">(</span><span class="n">chassisConvexMeshes</span><span class="p">[</span><span class="n">i</span><span class="p">]),</span> <span class="o">*</span><span class="n">chassisMaterials</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">chassisShape</span><span class="o">-></span><span class="n">setQueryFilterData</span><span class="p">(</span><span class="n">chassisQryFilterData</span><span class="p">);</span> + <span class="n">chassisShape</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">chassisSimFilterData</span><span class="p">);</span> + <span class="n">chassisShape</span><span class="o">-></span><span class="n">setLocalPose</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">));</span> + <span class="p">}</span> + + <span class="n">vehActor</span><span class="o">-></span><span class="n">setMass</span><span class="p">(</span><span class="n">chassisData</span><span class="p">.</span><span class="n">mMass</span><span class="p">);</span> + <span class="n">vehActor</span><span class="o">-></span><span class="n">setMassSpaceInertiaTensor</span><span class="p">(</span><span class="n">chassisData</span><span class="p">.</span><span class="n">mMOI</span><span class="p">);</span> + <span class="n">vehActor</span><span class="o">-></span><span class="n">setCMassLocalPose</span><span class="p">(</span><span class="n">PxTransform</span><span class="p">(</span><span class="n">chassisData</span><span class="p">.</span><span class="n">mCMOffset</span><span class="p">,</span><span class="n">PxQuat</span><span class="p">(</span><span class="n">PxIdentity</span><span class="p">)));</span> + + <span class="k">return</span> <span class="n">vehActor</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The significance of wheelSimFilterData, chassisSimFilterData, wheelQryFilterData and chassisQryFilterData shall be discussed in Section <a class="reference internal" href="#filtering"><em>Filtering</em></a>. Further, the link between the ordering of the wheel shapes in the above code and the function PxVehicleWheelsSimData::setWheelShapeMapping is clarified in Section <a class="reference internal" href="#wheel-pose"><em>Wheel Pose</em></a>.</p> +</div> +</div> +<div class="section" id="filtering"> +<span id="id8"></span><h3>Filtering<a class="headerlink" href="#filtering" title="Permalink to this headline">¶</a></h3> +<p>In this Section the concepts behind vehicle query and vehicle simulation filtering shall be described.</p> +<p>The key goal of scene query and simulation filtering for vehicles is to ensure that vehicles are supported by suspension spring forces without interference from wheel shape intersection. The requirements for filtering are then as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="mf">1.</span> <span class="n">wheel</span> <span class="n">shapes</span> <span class="n">must</span> <span class="n">not</span> <span class="n">hit</span> <span class="n">drivable</span> <span class="n">surfaces</span> +<span class="mf">2.</span> <span class="n">suspension</span> <span class="n">raycasts</span> <span class="n">can</span> <span class="n">hit</span> <span class="n">drivable</span> <span class="n">surfaces</span> +<span class="mf">3.</span> <span class="n">suspension</span> <span class="n">raycasts</span> <span class="n">must</span> <span class="n">not</span> <span class="n">hit</span> <span class="n">the</span> <span class="n">shapes</span> <span class="n">of</span> <span class="n">the</span> <span class="n">vehicle</span> <span class="n">issuing</span> <span class="n">the</span> <span class="n">raycasts</span> +</pre></div> +</div> +<p>Ensuring that wheel shapes don't hit drivable surfaces can be achieved with simulation filtering. This is discussed in more detail in Section <a class="reference internal" href="RigidBodyCollision.html#collisionfiltering"><em>Collision Filtering</em></a>. The vehicle snippets use the following simulation filter shader:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxFilterFlags</span> <span class="nf">VehicleFilterShader</span> +<span class="p">(</span><span class="n">PxFilterObjectAttributes</span> <span class="n">attributes0</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData0</span><span class="p">,</span> + <span class="n">PxFilterObjectAttributes</span> <span class="n">attributes1</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData1</span><span class="p">,</span> + <span class="n">PxPairFlags</span><span class="o">&</span> <span class="n">pairFlags</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">constantBlockSize</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">attributes0</span><span class="p">);</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">attributes1</span><span class="p">);</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">constantBlock</span><span class="p">);</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">constantBlockSize</span><span class="p">);</span> + + <span class="k">if</span><span class="p">(</span> <span class="p">(</span><span class="mi">0</span> <span class="o">==</span> <span class="p">(</span><span class="n">filterData0</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData1</span><span class="p">.</span><span class="n">word1</span><span class="p">))</span> <span class="o">&&</span> <span class="p">(</span><span class="mi">0</span> <span class="o">==</span> <span class="p">(</span><span class="n">filterData1</span><span class="p">.</span><span class="n">word0</span> <span class="o">&</span> <span class="n">filterData0</span><span class="p">.</span><span class="n">word1</span><span class="p">))</span> <span class="p">)</span> + <span class="k">return</span> <span class="n">PxFilterFlag</span><span class="o">::</span><span class="n">eSUPPRESS</span><span class="p">;</span> + + <span class="n">pairFlags</span> <span class="o">=</span> <span class="n">PxPairFlag</span><span class="o">::</span><span class="n">eCONTACT_DEFAULT</span><span class="p">;</span> + <span class="n">pairFlags</span> <span class="o">|=</span> <span class="n">PxPairFlags</span><span class="p">(</span><span class="n">PxU16</span><span class="p">(</span><span class="n">filterData0</span><span class="p">.</span><span class="n">word2</span> <span class="o">|</span> <span class="n">filterData1</span><span class="p">.</span><span class="n">word2</span><span class="p">));</span> + + <span class="k">return</span> <span class="n">PxFilterFlags</span><span class="p">();</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The snippets also apply simulation filter data to wheel shapes as follows:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxFilterData</span> <span class="n">wheelSimFilterData</span><span class="p">;</span> +<span class="n">wheelSimFilterData</span><span class="p">.</span><span class="n">word0</span> <span class="o">=</span> <span class="n">COLLISION_FLAG_WHEEL</span><span class="p">;</span> +<span class="n">wheelSimFilterData</span><span class="p">.</span><span class="n">word1</span> <span class="o">=</span> <span class="n">COLLISION_FLAG_WHEEL_AGAINST</span><span class="p">;</span> + +<span class="p">...</span> + +<span class="n">wheelShape</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">wheelSimFilterData</span><span class="p">);</span> +</pre></div> +</div> +<p>Finally, the following simulation filter data is applied to drivable surfaces:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxFilterData</span> <span class="n">simFilterData</span><span class="p">;</span> +<span class="n">simFilterData</span><span class="p">.</span><span class="n">word0</span> <span class="o">=</span> <span class="n">COLLISION_FLAG_GROUND</span><span class="p">;</span> +<span class="n">simFilterData</span><span class="p">.</span><span class="n">word1</span> <span class="o">=</span> <span class="n">COLLISION_FLAG_GROUND_AGAINST</span><span class="p">;</span> + +<span class="p">...</span> + +<span class="n">shapes</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">-></span><span class="n">setSimulationFilterData</span><span class="p">(</span><span class="n">simFilterData</span><span class="p">);</span> +</pre></div> +</div> +<p>The combination of collision flags (COLLISION_FLAG_WHEEL, COLLISION_FLAG_GROUND_AGAINST etc) and filter shader ensures that wheel shapes don't collide with drivable surfaces.</p> +<p>A remarkably similar process may be employed to configure the complementary scene query filters. This is accomplished in the vehicle snippets with the following code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">setupDrivableSurface</span><span class="p">(</span><span class="n">PxFilterData</span><span class="o">&</span> <span class="n">filterData</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">filterData</span><span class="p">.</span><span class="n">word3</span> <span class="o">=</span> <span class="p">(</span><span class="n">PxU32</span><span class="p">)</span><span class="n">DRIVABLE_SURFACE</span><span class="p">;</span> +<span class="p">}</span> + +<span class="kt">void</span> <span class="nf">setupNonDrivableSurface</span><span class="p">(</span><span class="n">PxFilterData</span><span class="o">&</span> <span class="n">filterData</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">filterData</span><span class="p">.</span><span class="n">word3</span> <span class="o">=</span> <span class="n">UNDRIVABLE_SURFACE</span><span class="p">;</span> +<span class="p">}</span> + +<span class="n">PxQueryHitType</span><span class="o">::</span><span class="n">Enum</span> <span class="n">WheelRaycastPreFilter</span> +<span class="p">(</span><span class="n">PxFilterData</span> <span class="n">filterData0</span><span class="p">,</span> <span class="n">PxFilterData</span> <span class="n">filterData1</span><span class="p">,</span> + <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">constantBlock</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">constantBlockSize</span><span class="p">,</span> + <span class="n">PxHitFlags</span><span class="o">&</span> <span class="n">queryFlags</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//filterData0 is the vehicle suspension raycast.</span> + <span class="c1">//filterData1 is the shape potentially hit by the raycast.</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">constantBlockSize</span><span class="p">);</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">constantBlock</span><span class="p">);</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">filterData0</span><span class="p">);</span> + <span class="n">PX_UNUSED</span><span class="p">(</span><span class="n">queryFlags</span><span class="p">);</span> + <span class="k">return</span> <span class="p">((</span><span class="mi">0</span> <span class="o">==</span> <span class="p">(</span><span class="n">filterData1</span><span class="p">.</span><span class="n">word3</span> <span class="o">&</span> <span class="n">DRIVABLE_SURFACE</span><span class="p">))</span> <span class="o">?</span> + <span class="n">PxQueryHitType</span><span class="o">::</span><span class="n">eNONE</span> <span class="o">:</span> <span class="n">PxQueryHitType</span><span class="o">::</span><span class="n">eBLOCK</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Each vehicle wheel is given filter data configured with setupNonDrivableSurface and passed to the vehicle with:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">wheelsSimData</span><span class="o">-></span><span class="n">setSceneQueryFilterData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">qryFilterData</span><span class="p">);</span> +</pre></div> +</div> +<p>The parameter filterData0 in WheelRaycastPreFilter corresponds to the parameter qryFilterData passed to the vehicle with PxVehiceWheelsSimData::setSceneQueryFilterData. The parameter filterData1, on the other hand, corresponds to the query filter data of a shape potentially hit by the raycast. In the vehicle snippets the shape of the drivable ground plane has scene query filter data configured with the function setupDrivableSurface. This satisfies the requirement that suspension raycasts can hit drivable surfaces. Vehicle shapes, on the other hand, are configured with setupNonDrivableSurface. This satisfies the restriction that suspension raycasts must not hit the vehicle issuing the raycasts but also prevents vehicles from driving on any other vehicles that might be added to the scene. This extra restriction could readily be avoided by employing a more complex filter shader that perhaps exploits unique IDs encoded in both the shape filter data and the filter data applied to the query itself. Care must be taken, however, to configure the filters to ensure that suspension raycasts only interact with the shapes of other vehicles.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">It is vital that WheelRaycastPreFilter returns PxQueryHitType::eBLOCK if a raycast hit is allowed for the filter data pair. Using PxQueryHitType::eBLOCK guarantees that each raycast returns either no hits or just the hit closest to the start point of the raycast. This is important because PxVehicleSuspensionRaycasts and PxVehicleUpdates expect a one-to-one correspondence between each wheel and each element in the PxRaycastQueryResult and PxRaycastHit arrays passed to the batch query.</p> +</div> +</div> +<div class="section" id="tire-friction-on-drivable-surfaces"> +<span id="id9"></span><h3>Tire Friction on Drivable Surfaces<a class="headerlink" href="#tire-friction-on-drivable-surfaces" title="Permalink to this headline">¶</a></h3> +<p>In this Section setting up tire types, drivable surface types, and tire friction on combinations of tire and surface type shall be discussed.</p> +<p>To implement a unique friction value for each combination of tire type and surface type it is first necessary to assign tire types to tires. In Section <a class="reference internal" href="#setupwheelssimulationdata"><em>setupWheelsSimulationData</em></a> a tire type was assigned to each tire:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//Set up the tires.</span> +<span class="n">PxVehicleTireData</span> <span class="n">tires</span><span class="p">[</span><span class="n">PX_MAX_NB_WHEELS</span><span class="p">];</span> +<span class="p">{</span> + <span class="c1">//Set up the tires.</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">numWheels</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">tires</span><span class="p">[</span><span class="n">i</span><span class="p">].</span><span class="n">mType</span> <span class="o">=</span> <span class="n">TIRE_TYPE_NORMAL</span><span class="p">;</span> + <span class="p">}</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Assigning a type to each surface is a little more complex. The basic idea is that each suspension raycast hit returns the PxMaterial of the shape hit by the raycast. With knowledge of a PxMaterial array it is possible to associate the type of a hit surface with the index of the PxMaterial array element that matches the material hit by the raycast. This lookup and the table of friction values is managed by the class PxVehicleDrivableSurfaceToTireFrictionPairs. To make the feature more general each element of the PxMaterial array is actually associated with a PxVehicleDrivableSurfaceType instance. This allows multiple PxMaterial instances to share the same surface type.</p> +<p>In the vehicle snippets the following code makes the association between PxMaterial and surface type and then associates each combination of tire and surface type with a friction value:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDrivableSurfaceToTireFrictionPairs</span><span class="o">*</span> <span class="nf">createFrictionPairs</span> + <span class="p">(</span><span class="k">const</span> <span class="n">PxMaterial</span><span class="o">*</span> <span class="n">defaultMaterial</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">PxVehicleDrivableSurfaceType</span> <span class="n">surfaceTypes</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> + <span class="n">surfaceTypes</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">mType</span> <span class="o">=</span> <span class="n">SURFACE_TYPE_TARMAC</span><span class="p">;</span> + + <span class="n">PxMaterial</span><span class="o">*</span> <span class="n">surfaceMaterials</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span> + <span class="n">surfaceMaterials</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">defaultMaterial</span><span class="p">;</span> + + <span class="n">PxVehicleDrivableSurfaceToTireFrictionPairs</span><span class="o">*</span> <span class="n">surfaceTirePairs</span> <span class="o">=</span> + <span class="n">PxVehicleDrivableSurfaceToTireFrictionPairs</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="n">MAX_NUM_TIRE_TYPES</span><span class="p">,</span> + <span class="n">MAX_NUM_SURFACE_TYPES</span><span class="p">);</span> + + <span class="n">surfaceTirePairs</span><span class="o">-></span><span class="n">setup</span><span class="p">(</span><span class="n">MAX_NUM_TIRE_TYPES</span><span class="p">,</span> <span class="n">MAX_NUM_SURFACE_TYPES</span><span class="p">,</span> + <span class="n">surfaceMaterials</span><span class="p">,</span> <span class="n">surfaceTypes</span><span class="p">);</span> + + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">MAX_NUM_SURFACE_TYPES</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</span> <span class="n">j</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">j</span> <span class="o"><</span> <span class="n">MAX_NUM_TIRE_TYPES</span><span class="p">;</span> <span class="n">j</span><span class="o">++</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">surfaceTirePairs</span><span class="o">-></span><span class="n">setTypePairFriction</span><span class="p">(</span><span class="n">i</span><span class="p">,</span><span class="n">j</span><span class="p">,</span><span class="n">gTireFrictionMultipliers</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">]);</span> + <span class="p">}</span> + <span class="p">}</span> + <span class="k">return</span> <span class="n">surfaceTirePairs</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">It is not necessary to provide an exhaustive array of all materials. If PxVehicleDrivableSurfaceToTireFrictionPairs has no knowledge of the hit material it assumes a value of zero for the surface type.</p> +</div> +<p>There is no upper bound on the friction values used in the PhysX vehicles SDK. Although the maximum value of friction that obeys the laws of physics is 1.0, the PhysX vehicles SDK purposefully does not enforce this rule. One reason for this is that the vehicle model is far from a complete description of a real vehicle, meaning that some liberties need to be taken with friction values to generate the desired behavior. A more complete model would certainly provide greater accuracy given a specific set of vehicle parameters but it is not at all clear that it would provide a greater range of editable and controllable behaviors or have the performance characteristics required for games. Another reason that friction is not clamped at 1.0 is that games typically simulate the physics update at 60Hz. This comes at a cost to numerical accuracy, especially when there are a number of transient tire effects that require KHz update frequencies. One source of numerical accuracy is the amplitude of oscillation of the suspension, which is governed in turn by the distance that the vehicle falls under gravity between each update. At KHz update frequencies this simulation artifact is acceptably small, but not at 60Hz. The last reason is that there is simply no need to impose the strict rules of friction on the vehicles SDK. This can allow interesting behaviors to be generated that would perhaps be impossible when constrained by the laws of rigid body and tire dynamics. Having said all this, however, the implemented model simulated at 60Hz ought to have enough integrity that only small tweaks above 1.0 should be necessary. If very large friction values are required, say greater than 2.0, then it is likely that something is wrong with the update order or perhaps very unphysical vehicle data has been used.</p> +<p>A PxVehicleDrivableSurfaceToTireFrictionPairs instance is passed as a function argument for each call to PxVehicleUpdates. Each instance of PxVehicleDrivableSurfaceToTireFrictionPairs need only persist for the duration of PxVehicleUpdates. It is perfectly legal to edit the tire types, materials and friction values in-between calls to PxVehicleUpdates. Editing any of these values while PxVehicleUpdates is still executing will lead to undefined behavior.</p> +</div> +<div class="section" id="vehicle-controls"> +<span id="id10"></span><h3>Vehicle Controls<a class="headerlink" href="#vehicle-controls" title="Permalink to this headline">¶</a></h3> +<p>In this Section setting the control values used to drive a vehicle shall be discussed.</p> +<p>The simplest and most direct way to set vehicle control values is to use the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxVehicleDriveDynData</span><span class="o">::</span><span class="n">setAnalogInput</span><span class="p">(</span><span class="k">const</span> <span class="n">PxReal</span> <span class="n">analogVal</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">type</span><span class="p">);</span> +</pre></div> +</div> +<p>One of the difficulties with vehicle dynamics in games is knowing how to filter the raw controller data in a way that results in pleasing handling. Players, for example, often accelerate by pressing very quickly on the accelerator trigger in a way would never happen in a real car. This rapid acceleration can have a counter-productive effect because the resulting wheel spin reduces the lateral and longitudinal forces that can be generated by the tire. To help overcome some of these problems some optional code has been provided to filter the control data from keyboard and gamepad.</p> +<p>A solution to the problem of filtering controller input data is to assign a rise and fall rate to each button or pad. For analog values under digital control it is possible to simply increase or decrease the analog value at a specified rate depending on whether the digital input is on or off. For analog values under analog control it makes more sense to blend from the previous input value to the current input at a specified rate. A slight complication to this simple model is that the difficulty of achieving a large steer angle at large speed must also be modeled. One technique to achieve this would be to model the forces from the tires' aligning moments and apply these to a steering linkage model. This sounds rather complicated and quite difficult to tune. A simpler solution might be to scale the filtered steer value by another value in range (0,1) that decreases at high speed. This simpler method has been implemented in the helper classes and functions.</p> +<p>Rise and fall rates for digital and analog control have been hard-coded in SnippetVehicle4W:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleKeySmoothingData</span> <span class="n">gKeySmoothingData</span><span class="o">=</span> +<span class="p">{</span> + <span class="p">{</span> + <span class="mf">3.0f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_ACCEL</span> + <span class="mf">3.0f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_BRAKE</span> + <span class="mf">10.0f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_HANDBRAKE</span> + <span class="mf">2.5f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_STEER_LEFT</span> + <span class="mf">2.5f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_STEER_RIGHT</span> + <span class="p">},</span> + <span class="p">{</span> + <span class="mf">5.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT__ACCEL</span> + <span class="mf">5.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT__BRAKE</span> + <span class="mf">10.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT__HANDBRAKE</span> + <span class="mf">5.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT_STEER_LEFT</span> + <span class="mf">5.0f</span> <span class="c1">//fall rate eANALOG_INPUT_STEER_RIGHT</span> + <span class="p">}</span> +<span class="p">};</span> + +<span class="n">PxVehiclePadSmoothingData</span> <span class="n">gPadSmoothingData</span><span class="o">=</span> +<span class="p">{</span> + <span class="p">{</span> + <span class="mf">6.0f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_ACCEL</span> + <span class="mf">6.0f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_BRAKE</span> + <span class="mf">12.0f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_HANDBRAKE</span> + <span class="mf">2.5f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_STEER_LEFT</span> + <span class="mf">2.5f</span><span class="p">,</span> <span class="c1">//rise rate eANALOG_INPUT_STEER_RIGHT</span> + <span class="p">},</span> + <span class="p">{</span> + <span class="mf">10.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT_ACCEL</span> + <span class="mf">10.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT_BRAKE</span> + <span class="mf">12.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT_HANDBRAKE</span> + <span class="mf">5.0f</span><span class="p">,</span> <span class="c1">//fall rate eANALOG_INPUT_STEER_LEFT</span> + <span class="mf">5.0f</span> <span class="c1">//fall rate eANALOG_INPUT_STEER_RIGHT</span> + <span class="p">}</span> +<span class="p">};</span> +</pre></div> +</div> +<p>A look-up table has also been specified to describe the maximum steer as a function of speed:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxF32</span> <span class="n">gSteerVsForwardSpeedData</span><span class="p">[</span><span class="mi">2</span><span class="o">*</span><span class="mi">8</span><span class="p">]</span><span class="o">=</span> +<span class="p">{</span> + <span class="mf">0.0f</span><span class="p">,</span> <span class="mf">0.75f</span><span class="p">,</span> + <span class="mf">5.0f</span><span class="p">,</span> <span class="mf">0.75f</span><span class="p">,</span> + <span class="mf">30.0f</span><span class="p">,</span> <span class="mf">0.125f</span><span class="p">,</span> + <span class="mf">120.0f</span><span class="p">,</span> <span class="mf">0.1f</span><span class="p">,</span> + <span class="n">PX_MAX_F32</span><span class="p">,</span> <span class="n">PX_MAX_F32</span><span class="p">,</span> + <span class="n">PX_MAX_F32</span><span class="p">,</span> <span class="n">PX_MAX_F32</span><span class="p">,</span> + <span class="n">PX_MAX_F32</span><span class="p">,</span> <span class="n">PX_MAX_F32</span><span class="p">,</span> + <span class="n">PX_MAX_F32</span><span class="p">,</span> <span class="n">PX_MAX_F32</span> +<span class="p">};</span> +<span class="n">PxFixedSizeLookupTable</span><span class="o"><</span><span class="mi">8</span><span class="o">></span> <span class="n">gSteerVsForwardSpeedTable</span><span class="p">(</span><span class="n">gSteerVsForwardSpeedData</span><span class="p">,</span><span class="mi">4</span><span class="p">);</span> +</pre></div> +</div> +<p>Using a PxVehicleDrive4WRawInputData instance it is straightforward to record the user inputs in the event a keyboard is used:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setDigitalAccel</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setDigitalBrake</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setDigitalHandbrake</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setDigitalSteerLeft</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setDigitalSteerRight</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setGearUp</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setGearDown</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +<p>or in the event that a gamepad is used:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setAnalogAccel</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setAnalogBrake</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setAnalogHandbrake</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setAnalogSteer</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setGearUp</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +<span class="n">gVehicleInputData</span><span class="p">.</span><span class="n">setGearDown</span><span class="p">(</span><span class="mf">1.0f</span><span class="p">);</span> +</pre></div> +</div> +<p>Here, gVehicleInputData is an instance of the vehicle SDK helper class PxVehicleDrive4WRawInputData.</p> +<p>The vehicle SDK offers two optional functions to smooth the keyboard or gamepad data and apply the smoothed input values to the PhysX vehicle. If the vehicle is controlled by digital inputs then the following function is used:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDrive4WSmoothDigitalRawInputsAndSetAnalogInputs</span><span class="p">(</span><span class="n">gKeySmoothingData</span><span class="p">,</span> + <span class="n">gSteerVsForwardSpeedTable</span><span class="p">,</span> <span class="n">carRawInputs</span><span class="p">,</span><span class="n">timestep</span><span class="p">,</span><span class="n">isInAir</span><span class="p">,(</span><span class="n">PxVehicleDrive4W</span><span class="o">&</span><span class="p">)</span><span class="n">focusVehicle</span><span class="p">);</span> +</pre></div> +</div> +<p>while gamepad controllers employ the following code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDrive4WSmoothAnalogRawInputsAndSetAnalogInputs</span><span class="p">(</span><span class="n">gCarPadSmoothingData</span><span class="p">,</span> + <span class="n">gSteerVsForwardSpeedTable</span><span class="p">,</span> <span class="n">carRawInputs</span><span class="p">,</span><span class="n">timestep</span><span class="p">,(</span><span class="n">PxVehicleDrive4W</span><span class="o">&</span><span class="p">)</span><span class="n">focusVehicle</span><span class="p">);</span> +</pre></div> +</div> +<p>The code above smoothes the controller inputs and applies them to a PxVehicleDrive4W instance. For other vehicle types the process is remarkably similar, except with complementary classes and functions designed for each vehicle type.</p> +</div> +<div class="section" id="vehicle-update"> +<span id="id11"></span><h3>Vehicle Update<a class="headerlink" href="#vehicle-update" title="Permalink to this headline">¶</a></h3> +<p>It has already been mentioned that vehicles are updated in two stages:</p> +<blockquote> +<div><ol class="arabic simple"> +<li>specific vehicle code that updates the vehicle internal dynamics and computes forces/torques to apply to the vehicle's rigid body representation</li> +<li>an SDK update that accounts for the applied forces/torques as well as collision with other scene bodies.</li> +</ol> +</div></blockquote> +<p>In Section <a class="reference internal" href="#introduction-to-vehicle-update"><em>Introduction To Vehicle Update</em></a> the functions used to perform the raycast and vehicle updates were introduced. In this Section these separate update phases will be discussed in more detail.</p> +<div class="section" id="raycast-and-update-ordering"> +<h4>Raycast and Update Ordering<a class="headerlink" href="#raycast-and-update-ordering" title="Permalink to this headline">¶</a></h4> +<p>Prior to the first time that a vehicle is updated in PxVehicleUpdates, it must have already performed suspension line raycasts at least once with PxVehicleSuspensionRaycasts. In subsequent updates it is not strictly necessary to issue fresh raycasts because each vehicle caches raycast hit planes that can be re-used. It is recommended that there is a one-to-one correspondence between raycast completion and updates for each vehicle except for the case of vehicles that only require a low level of detail. This might include cars that are far from the camera or where it is known that the vehicle is driving on geometry with high spatial coherence. Support for vehicles that require only a low level of detail is discussed in Section <a class="reference internal" href="#vehicle-level-of-detail"><em>Level of Detail</em></a>.</p> +<p>There is some freedom in the order in which raycasts can be issued relative to the vehicle dynamics update. In a real-world situation it might be that raycasts can be issued on a separate thread at the end of the update loop so that they are ready for the beginning of the next. However, this really all depends on the threading environment and the ordering of rigid body updates.</p> +</div> +<div class="section" id="wheel-pose"> +<span id="id12"></span><h4>Wheel Pose<a class="headerlink" href="#wheel-pose" title="Permalink to this headline">¶</a></h4> +<p>PxVehicleUpdates poses the wheels shapes of the vehicle's actor to take account of the steer, camber, and rotation angles. The computed pose also attempts to place the wheel geometry exactly on the contact plane identified by the raycast that was issued along the suspension line. To perform this function the PhysX Vehicles SDK needs to know which shapes of the actor correspond to each wheel of the vehicle. This is achieved with the function PxVehicleWheelsSimData::setWheelShapeMapping.</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">The vehicle SDK has a default mapping for each wheel that is equivalent to PxVehicleWheelsSimData::setWheelShapeMapping(i,i). This needs corrected if the layout of the shapes is different from the default pattern.</p> +</div> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">PxVehicleWheelsSimData::setWheelShapeMapping(i,-1) can be called to disable setting the local wheel pose. This is particularly useful if a wheel has no corresponding actor geometry.</p> +</div> +<p>The wheel pose is always within the limits imposed by PxVehicleSuspensionData::mMaxDroop and PxVehicleSuspensionData::mMaxCompression. If the suspension raycast hit plane requires the wheel to be placed beyond the compression limit the wheel will be placed at the compression limit and a rigid body constraint will handle the difference in the next SDK simulate() call.</p> +</div> +<div class="section" id="vehicle-state-queries"> +<span id="id13"></span><h4>Vehicle State Queries<a class="headerlink" href="#vehicle-state-queries" title="Permalink to this headline">¶</a></h4> +<p>Each vehicle stores persistent simulation data that is updated each time PxVehicleUpdates is called. Examples of persistent data include wheel rotation speeds, wheel rotation angle, and wheel rotation speed. Additionally, a large amount of non-persistent data is computed during each update. This non-persistent data is not stored in the vehicle's own data structures. Instead, a data buffer is passed to PxVehicleUpdates and queried after PxVehicleUpdates completes. Examples of non-persistent data include suspension jounce, tire force and raycast hit actor. The combination of these two data types allows an almost complete snapshot of the state of the vehicle and can be used to trigger secondary effects such as skid marks, engine and clutch audio, and smoke particles.</p> +<p>Persistent wheel data is stored in PxVehicleWheelsDynData, while persistent drive model data is stored in PxVehicleDriveDynData. The most useful functions are the following:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PX_FORCE_INLINE</span> <span class="n">PxReal</span> <span class="n">PxVehicleDriveDynData</span><span class="o">::</span><span class="n">getEngineRotationSpeed</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span> +<span class="n">PxReal</span> <span class="n">PxVehicleWheelsDynData</span><span class="o">::</span><span class="n">getWheelRotationSpeed</span><span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">wheelIdx</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span> +<span class="n">PxReal</span> <span class="n">PxVehicleWheelsDynData</span><span class="o">::</span><span class="n">getWheelRotationAngle</span><span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">wheelIdx</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span> +</pre></div> +</div> +<p>To record non-persistent simulation data so that it may be later be queried an extra function argument must be passed to PxVehicleUpdates. The following pseudo-code records non-persistent data for a single 4-wheeled car:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxWheelQueryResult</span> <span class="n">wheelQueryResults</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span> +<span class="n">PxVehicleWheelQueryResult</span> <span class="n">vehicleWheelQueryResults</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="p">{{</span><span class="n">wheelQueryResults</span><span class="p">,</span> <span class="mi">4</span><span class="p">}};</span> +<span class="n">PxVehicleUpdates</span><span class="p">(</span><span class="n">timestep</span><span class="p">,</span> <span class="n">gravity</span><span class="p">,</span> <span class="n">frictionPairs</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">vehicles</span><span class="p">,</span> <span class="n">vehicleWheelQueryResults</span><span class="p">);</span> +</pre></div> +</div> +<p>Here, a PxVehicleWheelQueryResult array, whose length equals at least the number of vehicles in the batched vehicles array, is passed to PxVehicleUpdates. Each PxVehicleWheelQueryResult instance has a pointer to a PxWheelQueryResult buffer, whose length equals at least the number of wheels in the vehicle. After PxVehicleUpdates is complete the state of each each vehicle wheel may be inspected.</p> +<p>It is not obligatory to record non-persistent data for later query. Indeed, it is perfect legal to associate a vehicle with a NULL data block to avoid storing non-persistent wheel data. This feature allows memory budgets to be targeted at the vehicles of highest interest.</p> +</div> +</div> +</div> +<div class="section" id="more-advanced-concepts"> +<h2>More Advanced Concepts<a class="headerlink" href="#more-advanced-concepts" title="Permalink to this headline">¶</a></h2> +<div class="section" id="vehicle-telemetry"> +<span id="id14"></span><h3>Vehicle Telemetry<a class="headerlink" href="#vehicle-telemetry" title="Permalink to this headline">¶</a></h3> +<p>The purpose of telemetry data is to expose the inner dynamics of the car and aid handling tuning through the use of telemetry graphs. In this Section initialization, collection, and rendering of telemetry data shall be discussed.</p> +<p>Telemetry data is recorded by calling the following function:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">PxVehicleUpdateSingleVehicleAndStoreTelemetryData</span> + <span class="p">(</span><span class="k">const</span> <span class="n">PxReal</span> <span class="n">timestep</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">gravity</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVehicleDrivableSurfaceToTireFrictionPairs</span><span class="o">&</span> <span class="n">vehicleDrivableSurfaceToTireFrictionPairs</span><span class="p">,</span> + <span class="n">PxVehicleWheels</span><span class="o">*</span> <span class="n">focusVehicle</span><span class="p">,</span> <span class="n">PxVehicleWheelQueryResult</span><span class="o">*</span> <span class="n">vehicleWheelQueryResults</span><span class="p">,</span> + <span class="n">PxVehicleTelemetryData</span><span class="o">&</span> <span class="n">telemetryData</span><span class="p">);</span> +</pre></div> +</div> +<p>The function above is identical to PxVehicleUpdates with the exception that it can only update a single vehicle at a time and takes an extra function argument telemetryData.</p> +<p>Setting up the telemetry data is relatively straightforward. In addition to storing the telemetry data streams, the PxVehicleTelemetryData structure also stores data describing the size, position, and color scheme of the graph. The following pseudo-code initializes and configures telemetry data for a 4-wheeled vehicle:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleTelemetryData</span><span class="o">*</span> <span class="n">myTelemetryData</span> <span class="o">=</span> <span class="n">PxVehicleTelemetryData</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span> + +<span class="k">const</span> <span class="n">PxF32</span> <span class="n">graphSizeX</span><span class="o">=</span><span class="mf">0.25f</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxF32</span> <span class="n">graphSizeY</span><span class="o">=</span><span class="mf">0.25f</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxF32</span> <span class="n">engineGraphPosX</span><span class="o">=</span><span class="mf">0.5f</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxF32</span> <span class="n">engineGraphPosY</span><span class="o">=</span><span class="mf">0.5f</span><span class="p">;</span> +<span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelGraphPosX</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span><span class="o">=</span><span class="p">{</span><span class="mf">0.75f</span><span class="p">,</span><span class="mf">0.25f</span><span class="p">,</span><span class="mf">0.75f</span><span class="p">,</span><span class="mf">0.25f</span><span class="p">};</span> +<span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelGraphPosY</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span><span class="o">=</span><span class="p">{</span><span class="mf">0.75f</span><span class="p">,</span><span class="mf">0.75f</span><span class="p">,</span><span class="mf">0.25f</span><span class="p">,</span><span class="mf">0.25f</span><span class="p">};</span> +<span class="k">const</span> <span class="n">PxVec3</span> <span class="nf">backgroundColor</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span><span class="mi">255</span><span class="p">,</span><span class="mi">255</span><span class="p">);</span> +<span class="k">const</span> <span class="n">PxVec3</span> <span class="nf">lineColorHigh</span><span class="p">(</span><span class="mi">255</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="k">const</span> <span class="n">PxVec3</span> <span class="nf">lineColorLow</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="mi">0</span><span class="p">);</span> +<span class="n">myTelemetryData</span><span class="o">-></span><span class="n">setup</span> + <span class="p">(</span><span class="n">graphSizeX</span><span class="p">,</span><span class="n">graphSizeY</span><span class="p">,</span> + <span class="n">engineGraphPosX</span><span class="p">,</span><span class="n">engineGraphPosY</span><span class="p">,</span> + <span class="n">wheelGraphPosX</span><span class="p">,</span><span class="n">wheelGraphPosY</span><span class="p">,</span> + <span class="n">backgroundColor</span><span class="p">,</span><span class="n">lineColorHigh</span><span class="p">,</span><span class="n">lineColorLow</span><span class="p">);</span> +</pre></div> +</div> +<p>The sizes, positions, and colors are all values that will be used to render the graphs. The exact values of these fields will depend on the coordinate system and color coding used to visualize the telemetry data.</p> +<p>In the above example, the coordinates have been configured to render an engine-related graph in the center of the screen under the assumption that (1,1) is the top left-hand side of the screen and (0,0) the bottom right-hand side of the screen. Screen coordinates have also been specified for rendering data associated with each of the four wheels.</p> +<p>The following enumerated lists detail the telemetry data that is collected:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> +<span class="p">{</span> + <span class="n">eCHANNEL_JOUNCE</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> + <span class="n">eCHANNEL_SUSPFORCE</span><span class="p">,</span> + <span class="n">eCHANNEL_TIRELOAD</span><span class="p">,</span> + <span class="n">eCHANNEL_NORMALISED_TIRELOAD</span><span class="p">,</span> + <span class="n">eCHANNEL_WHEEL_OMEGA</span><span class="p">,</span> + <span class="n">eCHANNEL_TIRE_FRICTION</span><span class="p">,</span> + <span class="n">eCHANNEL_TIRE_LONG_SLIP</span><span class="p">,</span> + <span class="n">eCHANNEL_NORM_TIRE_LONG_FORCE</span><span class="p">,</span> + <span class="n">eCHANNEL_TIRE_LAT_SLIP</span><span class="p">,</span> + <span class="n">eCHANNEL_NORM_TIRE_LAT_FORCE</span><span class="p">,</span> + <span class="n">eCHANNEL_NORM_TIRE_ALIGNING_MOMENT</span><span class="p">,</span> + <span class="n">eMAX_NUM_WHEEL_CHANNELS</span> +<span class="p">};</span> + +<span class="k">enum</span> +<span class="p">{</span> + <span class="n">eCHANNEL_ENGINE_REVS</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> + <span class="n">eCHANNEL_ENGINE_DRIVE_TORQUE</span><span class="p">,</span> + <span class="n">eCHANNEL_CLUTCH_SLIP</span><span class="p">,</span> + <span class="n">eCHANNEL_ACCEL_CONTROL</span><span class="p">,</span> + <span class="n">eCHANNEL_BRAKE_CONTROL</span><span class="p">,</span> + <span class="n">eCHANNEL_HANDBRAKE_CONTROL</span><span class="p">,</span> + <span class="n">eCHANNEL_STEER_CONTROL</span><span class="p">,</span> + <span class="n">eCHANNEL_GEAR_RATIO</span><span class="p">,</span> + <span class="n">eMAX_NUM_ENGINE_CHANNELS</span> +<span class="p">};</span> +</pre></div> +</div> +<p>Data is collected for suspension jounce, suspension force, tire load, normalized tire load, wheel rotation speed, tire friction, tire longitudinal slip, tire longitudinal force, tire lateral slip, tire lateral force, and tire aligning moment. Data is also collected separately for engine revs, engine drive torque, clutch slip, applied acceleration/brake/handbrake/steer, and gear ratio. For each graph all associated data is collected in separate graph channels that can be accessed after the update is complete.</p> +<p>Prior to rendering the graph of a particular wheel and channel the following pseudo-code is required:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxF32</span> <span class="n">xy</span><span class="p">[</span><span class="mi">2</span><span class="o">*</span><span class="n">PxVehicleGraph</span><span class="o">::</span><span class="n">eMAX_NB_SAMPLES</span><span class="p">];</span> +<span class="n">PxVec3</span> <span class="n">color</span><span class="p">[</span><span class="n">PxVehicleGraph</span><span class="o">::</span><span class="n">eMAX_NB_SAMPLES</span><span class="p">];</span> +<span class="kt">char</span> <span class="n">title</span><span class="p">[</span><span class="n">PxVehicleGraph</span><span class="o">::</span><span class="n">eMAX_NB_TITLE_CHARS</span><span class="p">];</span> +<span class="n">myTelemetryData</span><span class="o">-></span><span class="n">getWheelGraph</span><span class="p">(</span><span class="n">wheel</span><span class="p">).</span><span class="n">computeGraphChannel</span><span class="p">(</span><span class="n">PxVehicleWheelGraphChannel</span><span class="o">::</span><span class="n">eJOUNCE</span><span class="p">,</span> + <span class="n">xy</span><span class="p">,</span> <span class="n">color</span><span class="p">,</span> <span class="n">title</span><span class="p">);</span> +</pre></div> +</div> +<p>This code computes a sequence of screen coordinates in the format [x0,y0,x1,y1,x2,y2,....xn,yn] that represent the points of the specified graph channel of the engine's graph data. It also stores a color for each sample by choosing between lineColorHigh and lineColorLow depending on the value of the sample. Each graph channel stores the last 256 samples so that a history of each parameter may be rendered on the screen.</p> +<p>The PhysX Vehicles SDK does not render the graphs. This is an exercise left to the application because each has its own system for rendering debug information.</p> +</div> +<div class="section" id="vehicle-update-multi-threaded"> +<span id="id15"></span><h3>Vehicle Update Multi-Threaded<a class="headerlink" href="#vehicle-update-multi-threaded" title="Permalink to this headline">¶</a></h3> +<p>The PhysX Vehicles SDK can be used in a multi-threaded environment to take advantage of performance improvements arising from parallelism. The update steps proceed almost exactly as described in Section <a class="reference internal" href="#vehicle-update"><em>Vehicle Update</em></a> but with an extra sequential call to the function PxVehiclePostUpdates after all concurrent calls to PxVehicleSuspensionRaycasts and PxVehicleUpdates are complete. PxVehiclePostUpdates performs write operations normally executed in PxVehicleUpdates but which are not possible to efficiently or safely call when concurrency is employed.</p> +<p>PxVehicleSuspensionRaycasts is a thread-safe function and can be called concurrently without any modifications to the calling code with the exception, of course, of any code managing the tasks and threads that will execute the raycasts concurrently. On the other hand, PxVehicleUpdates as used in Section <a class="reference internal" href="#vehicle-update"><em>Vehicle Update</em></a> is not thread-safe and requires an extra PxVehicleConcurrentUpdateData array to be specified for it to be concurrently executed. When this extra data is specified PxVehicleUpdates defers a number of writes to PhysX actors that are involved in the vehicle updates. These deferred writes are stored in the PxVehicleConcurrentUpdateData array during all concurrent calls to PxVehicleUpdates and then executed sequentially in PxVehiclePostUpdates.</p> +<p>Sample code can be found in SnippetVehicleMultiThreading.</p> +</div> +<div class="section" id="tire-shaders"> +<span id="id16"></span><h3>Tire Shaders<a class="headerlink" href="#tire-shaders" title="Permalink to this headline">¶</a></h3> +<p>It is possible to replace the default tire model used by PhysX vehicles with custom models. This requires a shader function that can be set per-vehicle along with shader data that must be set per-wheel:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">PxVehicleWheelsDynData</span><span class="o">::</span><span class="n">setTireForceShaderFunction</span> + <span class="p">(</span><span class="n">PxVehicleComputeTireForce</span> <span class="n">tireForceShaderFn</span><span class="p">)</span> +<span class="kt">void</span> <span class="n">PxVehicleWheelsDynData</span><span class="o">::</span><span class="n">setTireForceShaderData</span> + <span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">tireId</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">tireForceShaderData</span><span class="p">)</span> +</pre></div> +</div> +<p>The shader function must implement this function prototype:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span><span class="n">PxVehicleComputeTireForce</span><span class="p">)</span> +<span class="p">(</span><span class="k">const</span> <span class="kt">void</span><span class="o">*</span> <span class="n">shaderData</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">tireFriction</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">longSlip</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">latSlip</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">camber</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelOmega</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">wheelRadius</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">recipWheelRadius</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">restTireLoad</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">normalisedTireLoad</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">tireLoad</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxF32</span> <span class="n">gravity</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">recipGravity</span><span class="p">,</span> + <span class="n">PxF32</span><span class="o">&</span> <span class="n">wheelTorque</span><span class="p">,</span> <span class="n">PxF32</span><span class="o">&</span> <span class="n">tireLongForceMag</span><span class="p">,</span> <span class="n">PxF32</span><span class="o">&</span> <span class="n">tireLatForceMag</span><span class="p">,</span> <span class="n">PxF32</span><span class="o">&</span> <span class="n">tireAlignMoment</span><span class="p">);</span> +</pre></div> +</div> +<p>The vehicle update code will call the shader function for each wheel with the shader data for that wheel.</p> +</div> +<div class="section" id="vehicle-types"> +<span id="id17"></span><h3>Vehicle Types<a class="headerlink" href="#vehicle-types" title="Permalink to this headline">¶</a></h3> +<p>The PhysX Vehicle SDK supports four types of vehicle: PxVehicleDrive4W, PxVehicleDriveNW, PxVehicleDriveTank and PxVehicleNoDrive. In most cases PxVehicleDrive4W will be the best choice for rally cars, street cars and racing cars. PxVehicleDriveNW is very similar to PxVehicleDrive4W except that it has the advantage that it allows all wheels to be coupled to the differential. This generality means that the differential models of PxVehicleDriveNW cannot match the range or detail supported by PxVehicleDrive4W. PxVehicleDriveTank implements a simple but efficient tank model by constraining the left and right wheel speeds to mimic the effect of tank tracks. Lastly, PxVehicleNoDrive implements a vehicle that is simply a rigid body with suspensions and wheels and tires. The idea here is to allow custom drive models such as skateboards and hovercraft to be implemented using PhysX vehicles.</p> +<div class="section" id="pxvehicledrive4w"> +<h4>PxVehicleDrive4W<a class="headerlink" href="#pxvehicledrive4w" title="Permalink to this headline">¶</a></h4> +<p>The class PxVehicleDrive4W has already been discussed in some detail but the discussion so far has focused on 4-wheeled vehicles. In the following Sections PxVehicleDrive4W shall be discussed with special reference to instances with less than and more than 4 wheels.</p> +<div class="section" id="wheeled-cars"> +<span id="threewheeled"></span><h5>3-Wheeled Cars<a class="headerlink" href="#wheeled-cars" title="Permalink to this headline">¶</a></h5> +<p>Utility functions have been provided to quickly configure 3-wheeled cars. The basic idea is to start with a 4-wheeled car and then disable one of the wheels:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">PxVehicle4WEnable3WTadpoleMode</span><span class="p">(</span><span class="n">PxVehicleWheelsSimData</span><span class="o">&</span> <span class="n">wheelsSimData</span><span class="p">,</span> + <span class="n">PxVehicleWheelsDynData</span><span class="o">&</span> <span class="n">wheelsDynData</span><span class="p">,</span> <span class="n">PxVehicleDriveSimData4W</span><span class="o">&</span> <span class="n">driveSimData</span><span class="p">);</span> +<span class="kt">void</span> <span class="nf">PxVehicle4WEnable3WDeltaMode</span><span class="p">(</span><span class="n">PxVehicleWheelsSimData</span><span class="o">&</span> <span class="n">wheelsSimData</span><span class="p">,</span> + <span class="n">PxVehicleWheelsDynData</span><span class="o">&</span> <span class="n">wheelsDynData</span><span class="p">,</span> <span class="n">PxVehicleDriveSimData4W</span><span class="o">&</span> <span class="n">driveSimData</span><span class="p">);</span> +</pre></div> +</div> +<p>These functions ensure that no raycast hits are returned for the disabled wheel and additionally do some other work to decouple the disabled wheel from the differential, disable ackermann correction, re-position the opposite remaining wheel to the center of the axle, and adjust the suspension of the opposite remaining wheel to compensate for the missing suspension of the disabled wheel. Further wheels could in theory be removed with custom code to create a vehicle with 1 or 2 effective wheels. At that point, however, extra balancing code would be required to prevent the vehicle falling over.</p> +<p>Some care must be taken when removing a wheel because the PxVehicleUpdates function has a number of requirements that must be satisfied for all vehicles. The first requirement is that any wheel that has been disabled must not be associated with a PxShape. This is a safety feature that prevents PxVehicleUpdates attempting to set the local pose of a PxShape that may no longer be valid. The function PxVehicleWheelsSimData::setWheelShapeMapping can be used to satisfy this requirement. The second requirement is that any wheel that has been disabled must have zero wheel rotation speed. This can be satisfied by calling PxVehicleWheelsDynData::setWheelRotationSpeed for the relevant wheel. The final requirement is that disabled wheels must receive no drive torque. For tanks this requirement can actually be ignored because it is automatically enforced with custom tank code called by the PxVehicleUpdates function. For vehicles of type PxVehicleNoDrive the requirement on drive torque is fulfilled by ensuring that PxVehicleNoDrive::setDriveTorque is never called with a non-zero torque value. Further, the drive torque requirement can be readily fulfilled for vehicles of type PxVehicleDriveNW by ensuring that the differential is disconnected from the disabled wheel. This is achieved using the function PxVehicleDifferentialNWData::setDrivenWheel.</p> +<p>Configuring the differential of a PxVehicle4W to ensure that no drive torque is delivered to a disabled wheel is a little more complex because there are many different ways to achieve this. If the wheel is not a driven wheel then disabling the wheel automatically satisfies the drive torque requirement because such wheels can never be connected to the differential. On the other hand, if the wheel has index eFRONT_LEFT or eFRONT_RIGHT or eREAR_LEFT or eREAR_RIGHT then the differential does need to be modified to enforce the requirement. One way to do this is to set up the differential so that it delivers torque to only the rear(front) wheels if a front(rear) wheel has been disabled. This can be readily implemented by selecting front-wheel drive mode or rear-wheel drive mode as appropriate:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDifferential4WData</span> <span class="n">diff</span> <span class="o">=</span> <span class="n">myVehicle</span><span class="p">.</span><span class="n">getDiffData</span><span class="p">();</span> +<span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_LEFT</span> <span class="o">==</span> <span class="n">wheelToDisable</span> <span class="o">||</span> + <span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_RIGHT</span> <span class="o">==</span> <span class="n">wheelToDisable</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_FRONTWD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_OPEN_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_OPEN_FRONTWD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mBias</span> <span class="o">=</span> <span class="mf">1.3f</span><span class="p">;</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mRearLeftRightSplit</span> <span class="o">=</span> <span class="mf">0.5f</span><span class="p">;</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">=</span> <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_REARWD</span><span class="p">;</span> + <span class="c1">//could also be PxVehicleDifferential4WData::eDIFF_TYPE_OPEN_REARWD;</span> + <span class="p">}</span> +<span class="p">}</span> +<span class="k">else</span> <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_LEFT</span> <span class="o">==</span> <span class="n">wheelToDisable</span> <span class="o">||</span> + <span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_RIGHT</span> <span class="o">==</span> <span class="n">wheelToDisable</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_REARWD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_OPEN_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_OPEN_REARWD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mBias</span> <span class="o">=</span> <span class="mf">1.3f</span><span class="p">;</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mFronteftRightSplit</span> <span class="o">=</span> <span class="mf">0.5f</span><span class="p">;</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">=</span> <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_FRONTWD</span><span class="p">;</span> + <span class="c1">//could also be PxVehicleDifferential4WData::eDIFF_TYPE_OPEN_FRONTWD;</span> + <span class="p">}</span> +<span class="p">}</span> +<span class="n">myVehicle</span><span class="p">.</span><span class="n">setDiffData</span><span class="p">(</span><span class="n">diff</span><span class="p">);</span> +</pre></div> +</div> +<p>In some situations limiting the drove torque to just the front or rear wheels might not be acceptable. If only a single wheel has been disabled then it is possible to engage a drive mode where 3 wheels are driven. This can be achieved by modifying a differential that delivers torque to all four wheels (eDIFF_TYPE_LS_4WD or eDIFF_TYPE_OPEN_4WD) so that torque is only delivered to 3 wheels:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDifferential4WData</span> <span class="n">diff</span> <span class="o">=</span> <span class="n">myVehicle</span><span class="p">.</span><span class="n">getDiffData</span><span class="p">();</span> +<span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_LEFT</span> <span class="o">==</span> <span class="n">wheelToDisable</span> <span class="o">||</span> + <span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_RIGHT</span> <span class="o">==</span> <span class="n">wheelToDisable</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_OPEN_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eFRONT_LEFT</span> <span class="o">==</span> <span class="n">wheelToDisable</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mFrontLeftRightSplit</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">;</span> + <span class="p">}</span> + <span class="k">else</span> + <span class="p">{</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mFrontLeftRightSplit</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +<span class="k">else</span> <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_LEFT</span> <span class="o">==</span> <span class="n">wheelToDisable</span> <span class="o">||</span> + <span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_RIGHT</span> <span class="o">==</span> <span class="n">wheelToDisable</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_LS_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span> <span class="o">||</span> + <span class="n">PxVehicleDifferential4WData</span><span class="o">::</span><span class="n">eDIFF_TYPE_OPEN_4WD</span> <span class="o">==</span> <span class="n">diff</span><span class="p">.</span><span class="n">mType</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">if</span><span class="p">(</span><span class="n">PxVehicleDrive4WWheelOrder</span><span class="o">::</span><span class="n">eREAR_LEFT</span> <span class="o">==</span> <span class="n">wheelToDisable</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mRearLeftRightSplit</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">;</span> + <span class="p">}</span> + <span class="k">else</span> + <span class="p">{</span> + <span class="n">diff</span><span class="p">.</span><span class="n">mRearLeftRightSplit</span> <span class="o">=</span> <span class="mf">1.0f</span><span class="p">;</span> + <span class="p">}</span> + <span class="p">}</span> +<span class="p">}</span> +<span class="n">myVehicle</span><span class="p">.</span><span class="n">setDiffData</span><span class="p">(</span><span class="n">diff</span><span class="p">);</span> +</pre></div> +</div> +<p>In some situations it will make sense to disable Ackermann steer correction if the disabled wheel was able to steer. In particular, if the remaining wheel of the front or rear axle is re-positioned so that it is at the center of the axle then it would almost certainly follow that Ackermann correction would be disabled. This can be achieved by setting the accuracy to zero (PxVehicleAckermannGeometryData::mAccuracy). The role of Ackermann steer correction, however, really needs to be determined on a case by case basis.</p> +</div> +<div class="section" id="n-wheeled-cars"> +<span id="id18"></span><h5>N-Wheeled Cars<a class="headerlink" href="#n-wheeled-cars" title="Permalink to this headline">¶</a></h5> +<p>In addition to removing wheels from a vehicle, it is also possible to construct a PxVehicleDrive4W with more than 4 wheels but with the caveat that only 4 wheels may be driven. As a consequence of this caveat the functionality of the extra wheels is slightly limited compared to the first 4 wheels. More specifically, only the first 4 wheels are connected to the differential or the steering; that is, only the first block of 4 wheels can experience a drive torque or a steer angle and only the first block of 4 wheels participate in the Ackermann steering correction. As a consequence, the extra wheels play an identical role to the rear wheels of a 4-wheeled car that has front-wheel drive or the front wheels or a 4-wheeled car that has rear-wheel drive. Adding extra wheels does not preclude the ability to call PxVehicle4WEnable3WTadpoleMode or PxVehicle4WEnable3WDeltaMode. These functions, however, are hard-coded to disable one of the 4 wheels that could be connected to the steering and driven through the differential.</p> +<p>The following pseudo-code illustrates the key steps in the creation of a 6-wheeled PxVehicleDrive4W vehicle:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleWheelsSimData</span><span class="o">*</span> <span class="n">wheelsSimData</span><span class="o">=</span><span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> +<span class="n">PxVehicleDriveSimData4W</span> <span class="n">driveSimData</span><span class="p">;</span> +<span class="n">setupSimData</span><span class="p">(</span><span class="n">wheelsSimData</span><span class="p">,</span><span class="n">driveSimData</span><span class="p">);</span> +<span class="n">PxVehicleDrive4W</span><span class="o">*</span> <span class="n">car</span> <span class="o">=</span> <span class="n">PxVehicleDrive4W</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">vehActor</span><span class="o">=</span><span class="n">createVehicleActor6W</span><span class="p">();</span> +<span class="n">car</span><span class="o">-></span><span class="n">setup</span><span class="p">(</span><span class="o">&</span><span class="n">physics</span><span class="p">,</span><span class="n">vehActor</span><span class="p">,</span><span class="o">*</span><span class="n">wheelsSimData</span><span class="p">,</span><span class="n">driveSimData</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="pxvehicledrivenw"> +<span id="id19"></span><h4>PxVehicleDriveNW<a class="headerlink" href="#pxvehicledrivenw" title="Permalink to this headline">¶</a></h4> +<p>While the PxVehicleDrive4W allows cars with any number of wheels to be created and simulated it only allows 4 of those wheels to be driven by engine torques via the differential. The vehicle type PxVehicleDriveNW has been introduced to solve this specific limitation. This vehicle class makes use of the differential type PxVehicleDifferentialNW, a class that allows any or all of the vehicle's wheels to be coupled to the differential with the limitation that the torque available at the differential is always divided equally among the wheels that are coupled to the differential. The generality of PxVehicleNW precludes advanced features such as limited slip differentials and Ackermann steering correction, meaning that only a simple equal-split differential model can be provided at present.</p> +<p>The following pseudo-code illustrates the key steps in the creation of a 6-wheeled PxVehicleDriveNW vehicle:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleWheelsSimData</span><span class="o">*</span> <span class="n">wheelsSimData</span><span class="o">=</span><span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> +<span class="n">PxVehicleDriveSimDataNW</span> <span class="n">driveSimData</span><span class="p">;</span> +<span class="n">setupSimData</span><span class="p">(</span><span class="n">wheelsSimData</span><span class="p">,</span><span class="n">driveSimData</span><span class="p">);</span> +<span class="n">PxVehicleDriveNW</span><span class="o">*</span> <span class="n">car</span> <span class="o">=</span> <span class="n">PxVehicleDriveNW</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">6</span><span class="p">);</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">vehActor</span><span class="o">=</span><span class="n">createVehicleActorNW</span><span class="p">();</span> +<span class="n">car</span><span class="o">-></span><span class="n">setup</span><span class="p">(</span><span class="o">&</span><span class="n">physics</span><span class="p">,</span><span class="n">vehActor</span><span class="p">,</span><span class="o">*</span><span class="n">wheelsSimData</span><span class="p">,</span><span class="n">driveSimData</span><span class="p">,</span><span class="mi">6</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="pxvehicledrivetank"> +<span id="id20"></span><h4>PxVehicleDriveTank<a class="headerlink" href="#pxvehicledrivetank" title="Permalink to this headline">¶</a></h4> +<p>The PhysX vehicle SDK also supports tanks through the use of the PxVehicleDriveTank class. Tanks are different to multi-wheeled vehicles in that the wheels are all driven through the differential in a way that ensures that all the wheels on the left-hand side have the same speed, and all the wheels on the right-hand have the same speed. This extra constraint on wheel speed mimics the effect of the caterpillar tracks but avoids the expense of simulating the jointed track structure. Adding the geometry of the caterpillar tracks is as easy as adding an actor shape down each side and setting up the collision and query filters as appropriate for the tracks. The motion of the caterpillar tracks could be rendered with a scrolling texture, safe in the knowledge that all wheels have the same speed, just as though they were properly constrained by the track rotation.</p> +<p>Creating a PxVehicleDriveTank instance is very similar to creating a PxVehicleDrive4W instance with the exception that tanks have no concept of extra wheels that are not connected to the differential: all tank wheels are driven. The following code illustrates how to set up a 12-wheeled tank:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleWheelsSimData</span><span class="o">*</span> <span class="n">wheelsSimData</span> <span class="o">=</span> <span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">12</span><span class="p">);</span> +<span class="n">PxVehicleDriveSimData4W</span> <span class="n">driveSimData</span><span class="p">;</span> +<span class="n">setupTankSimData</span><span class="p">(</span><span class="n">wheelsSimData</span><span class="p">,</span><span class="n">driveSimData</span><span class="p">);</span> +<span class="n">PxVehicleDriveTank</span><span class="o">*</span> <span class="n">tank</span> <span class="o">=</span> <span class="n">PxVehicleDriveTank</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">12</span><span class="p">);</span> +<span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">vehActor</span><span class="o">=</span><span class="n">createVehicleActor12W</span><span class="p">();</span> +<span class="n">tank</span><span class="o">-></span><span class="n">setup</span><span class="p">(</span><span class="o">&</span><span class="n">physics</span><span class="p">,</span><span class="n">vehActor</span><span class="p">,</span><span class="o">*</span><span class="n">wheelsSimData</span><span class="p">,</span><span class="n">tankDriveSimData</span><span class="p">,</span><span class="mi">12</span><span class="p">);</span> +</pre></div> +</div> +<p>Controlling a tank is quite different to controlling a car because tanks have a completely different steering mechanism: the turning action of a tank arises from the difference in left and right wheel speeds, while cars turn by the action of a steering wheel that orientates the front wheels relative to the forward motion of the vehicle. This requires quite a different set of helper classes and functions to smooth the control inputs:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="mf">1.</span> <span class="n">PxVehicleDriveTankRawInputData</span> +<span class="mf">2.</span> <span class="n">PxVehicleDriveTankSmoothDigitalRawInputsAndSetAnalogInputs</span> +<span class="mf">3.</span> <span class="n">PxVehicleDriveTankSmoothAnalogRawInputsAndSetAnalogInputs</span> +</pre></div> +</div> +<p>PhysX tanks currently support two drive models: eSTANDARD and eSPECIAL. The drive model eSPECIAL allows the tank tracks to rotate in different directions, while eSTANDARD does not. These two modes result in quite different turning actions. Drive model eSTANDARD simulates the usual turning action of a tank: pushing forward on the left(right) stick drives the left(right) wheels forward, while pulling back on the right(left) stick applies the brake to the right(left) wheels. eSPECIAL, on the other hand, simulates a more exotic turning action where pushing back on the right(left) stick drives the right(left) wheels backwards. This can result in a turning circle focused at the center of the tank. The smallest possible turning circle of a tank in eSTANDARD will have a focus at a point along one of the caterpillar tracks, depending on whether the tank is turning left or right.</p> +</div> +<div class="section" id="pxvehiclenodrive"> +<h4>PxVehicleNoDrive<a class="headerlink" href="#pxvehiclenodrive" title="Permalink to this headline">¶</a></h4> +<p>The class PxVehicleNoDrive has been introduced to provide a close approximation to backwards compatibility with the interface to the 2.8.x NxWheelShape class. It is essentially a rigid body with N suspension/wheel/tire units attached. It's behavior is identical to that of a PxVehicleDrive4W which is permanently in neutral gear so that the engine has no influence on the wheels and the wheels are coupled only through the motion of the rigid body. This comes, of course, without the storage overhead of Ackermann steering correction data, engine torque curve data etc. The idea is that users can develop their own drive model on top of already existing vehicle code to manage the suspension raycasts, tire and suspension force computation, and PhysX SDK integration.</p> +<p>The key functions are the application of per wheel drive and brake torques and per wheel steer angles:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/**</span> +<span class="cm">\brief Set the brake torque to be applied to a specific wheel</span> +<span class="cm">*/</span> +<span class="kt">void</span> <span class="nf">setBrakeTorque</span><span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">id</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">brakeTorque</span><span class="p">);</span> + +<span class="cm">/**</span> +<span class="cm">\brief Set the drive torque to be applied to a specific wheel</span> +<span class="cm">*/</span> +<span class="kt">void</span> <span class="nf">setDriveTorque</span><span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">id</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">driveTorque</span><span class="p">);</span> + +<span class="cm">/**</span> +<span class="cm">\brief Set the steer angle to be applied to a specific wheel</span> +<span class="cm">*/</span> +<span class="kt">void</span> <span class="nf">setSteerAngle</span><span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">id</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">steerAngle</span><span class="p">);</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="si-units"> +<h3>SI Units<a class="headerlink" href="#si-units" title="Permalink to this headline">¶</a></h3> +<p>The discussion so far has assumed that distance is measured in metres, that mass is measured in kilograms, and that time is measured in seconds. Further, the default values of all relevant vehicle components have been set under the assumption that SI Units will be adopted. An example of such a a default parameter is the maximum braking torque value. Inspection of the constructor for PxVehicleWheelData reveals a value of 1500 for mMaxBrakeTorque. This number actually represents a value of 1500 "Kilogram Metres-Squared Per Second-Squared" (an alternative way of expressing this is 1500 "Newton Metres"). An important question is how to set up a vehicle with meaningful values if SI units are not adopted. The purpose of this Section is to illustrate the steps required. In particular, the case where distance is measured in centimeters rather than metres will be used as an example. This particular deviation from the adoption of SI Units is probably the most common one in game development, arising from the units of distance in the chosen 3D modeling package.</p> +<p>Vehicle parameters whose value is dependent on the length scale fall into two categories: those that can theoretically be measured with a ruler and those with more complex units involving combinations of other properties such as mass or time or even powers of distance. The former category includes data fields such as wheel radius or maximum suspension droop, while the latter category includes data fields such as maximum braking torque or wheel moment of inertia.</p> +<p>The following is an exhaustive list of vehicle parameters that can theoretically be measured solely from vehicle geometry:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleChassisData</span><span class="o">::</span><span class="n">mCMOffset</span> + +<span class="n">PxVehicleAckermannGeometryData</span><span class="o">::</span><span class="n">mFrontWidth</span> + +<span class="n">PxVehicleAckermannGeometryData</span><span class="o">::</span><span class="n">mRearWidth</span> + +<span class="n">PxVehicleAckermannGeometryData</span><span class="o">::</span><span class="n">mAxleSeparation</span> + +<span class="n">PxVehicleWheelData</span><span class="o">::</span><span class="n">mRadius</span> + +<span class="n">PxVehicleWheelData</span><span class="o">::</span><span class="n">mWidth</span> + +<span class="n">PxVehicleSuspensionData</span><span class="o">::</span><span class="n">mMaxCompression</span> + +<span class="n">PxVehicleSuspensionData</span><span class="o">::</span><span class="n">mMaxDroop</span> + +<span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">setSuspForceAppPointOffset</span> + +<span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">setTireForceAppPointOffset</span> + +<span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">setWheelCentreOffset</span> +</pre></div> +</div> +<p>It is useful to note that all the above parameters have default value of zero; that is, independent of length scale they must always be set with measured values in the corresponding length scale if a legal vehicle is to be successfully instantiated.</p> +<p>Setting parameters that involve more complex combinations of length scale require slightly more thought than those featured in the list above. A simple rule of thumb is that any parameter that has units linear with distance must be scaled by the number of length units that is equivalent to 1 meter, while any parameter that has units involving the square of distance must be scaled by the square of the number of length units that is equivalent to 1 meter. A wheel braking torque of 1500 kilograms metres-squared per second-squared, for example, is equivalent to 1500*100*100 kilograms centimeters-squared per second-squared. Consequently, when centimeters is used as the length scale a good initial guess for wheel braking torque is 15000000 [kilograms centimeters-squared per second-squared]. If inches are used as the length scale then a good initial guess for the wheel braking torque would be 1500*39.37*39.37 (= 2324995.35) [kilograms inches-squared per second-squared].</p> +<p>Each non-dimensionless parameter has been described with the corresponding SI Units in PxVehicleComponents.h. The following is an exhaustive list of vehicle parameters that are indirect expressions of distance scale:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleEngineData</span><span class="o">::</span><span class="n">mMOI</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span><span class="p">)</span> + +<span class="n">PxVehicleEngineData</span><span class="o">::</span><span class="n">mPeakTorque</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">2</span><span class="p">)</span> + +<span class="n">PxVehicleEngineData</span><span class="o">::</span><span class="n">mDampingRateFullThrottle</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">1</span><span class="p">)</span> + +<span class="n">PxVehicleEngineData</span><span class="o">::</span><span class="n">mDampingRateZeroThrottleClutchEngaged</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">1</span><span class="p">)</span> + +<span class="n">PxVehicleEngineData</span><span class="o">::</span><span class="n">mDampingRateZeroThrottleClutchDisengaged</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">1</span><span class="p">)</span> + +<span class="n">PxVehicleClutchData</span><span class="o">::</span><span class="n">mStrength</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">1</span><span class="p">)</span> + +<span class="n">PxVehicleWheelData</span><span class="o">::</span><span class="n">mDampingRate</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">1</span><span class="p">)</span> + +<span class="n">PxVehicleWheelData</span><span class="o">::</span><span class="n">mMaxBrakeTorque</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">2</span><span class="p">)</span> + +<span class="n">PxVehicleWheelData</span><span class="o">::</span><span class="n">mMaxHandBrakeTorque</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span> <span class="n">s</span><span class="o">^-</span><span class="mi">2</span><span class="p">)</span> + +<span class="n">PxVehicleWheelData</span><span class="o">::</span><span class="n">mMOI</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span><span class="p">)</span> + +<span class="n">PxVehicleChassisData</span><span class="o">::</span><span class="n">mMOI</span> <span class="p">(</span><span class="n">kg</span> <span class="n">m</span><span class="o">^</span><span class="mi">2</span><span class="p">)</span> +</pre></div> +</div> +<p>All but the last three of the above parameters have non-zero initial values in their associated constructors. This means that a good guess for their initial value can be found by multiplying the value expressed in SI Units with either the number of length units equivalent to 1 meter or the square of the number of length units that are equivalent to 1 meter.</p> +<p>It is important to note that the wheel handbrake torque has a default value of zero because not all wheels respond to the handbrake torque. A good guess for the handbrake torque is simply the value of the wheel braking torque, perhaps multiplied by between 1.0 and 2.0 to ensure that the handbrake is stronger than the brake.</p> +<p>The wheel moment of inertia and chassis moment of inertia are typically computed from the wheel radius and chassis dimensions so naturally reflect the length scale that is used in the simulation. If values are taken from manufacturer data it is important to ensure that the units of the manufacturer data are commensurate with the remainder of the vehicle data fields or to perform the appropriate unit conversion.</p> +<p>A number of functions also have parameters that are functions of length scale. The following is an exhaustive list of such functions:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">setSubStepCount</span> + +<span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">setMinLongSlipDenominator</span> + +<span class="n">PxVehicleSetMaxHitActorAcceleration</span> +</pre></div> +</div> +<p>Some care is required to set the threshold speed in PxVehicleWheels::setSubStepCount. Here, it is the case that the default threshold speed is 5.0 metres per second. With centimeters the chosen length scale a value of 500 [centimeters per second] should be passed to achieve the equivalent behavior, or with inches as the chosen length scale a value of 5*39.37 (= 196.85) [inches per second] is required. The same process must also be applied to PxVehicleWheelsSimData::setMinLongSlipDenominator. Here, the default is 4.0 metres per second. If centimeters is the adopted scale then the equivalent value is 400 [centimeters per second], while 4*39.37 (=157.48) [inches per second] is required if inches is the chosen scale. PxVehicleSetMaxHitActorAcceleration takes a value that scales linearly with the length scale. If the desired maximum acceleration is 10 metres per second per second then that would be scaled to 10*100 centimetres per second per second in centimetres scale. With inches as the length scale the equivalent value would be 10*39.37 inches per second per second.</p> +<p>The PhysX Vehicle SDK supports any system of units with the caveat that all data supplied must conform to the same unit system. Further, the default data values, although strictly expressed in the SI unit system, can be used as a guide to estimate sensible values in any unit system for almost any conceivable vehicle. A quick way to do this would be to decide if, say, a truck would have a stronger handbrake than the handbrake of a family car. Now, the default data approximates that of a standard family car so it might be a good estimate to start with the truck having a handbrake that is perhaps 25% stronger; that is, 5000 kilograms metres-squared per second-squared. If centimeters are the chosen length scale then a quick conversion can be performed by noting that 1 meter is equal to 100 centimeters, leading to the brake torque being set as 5000*100*100 kilograms centimeters-squared per second-squared. If the natural unit of mass is the gram then noting that 1 kilogram is 1000 grams leads to an equivalent value of 5000*1000 grams metres-squared per second-squared. This rule can be repeated for all vehicle data fields by simply noting the default value and the SI units in the relevant class constructor and then performing the conversion to the chosen unit system.</p> +<p>The PhysX Vehicle SDK depends on a number of threshold values that are functions of length scale. These are set with the function PxInitVehicleSDK and uses the PxTolerancesScale values that have already been already configured for the PhysX SDK. If PxInitVehicleSDK is not called prior to the first call to PxVehicleUpdates a warning will be passed to the PhysX error stream.</p> +</div> +<div class="section" id="level-of-detail"> +<span id="vehicle-level-of-detail"></span><h3>Level of Detail<a class="headerlink" href="#level-of-detail" title="Permalink to this headline">¶</a></h3> +<p>It seems sensible to attempt to save valuable clock cycles for vehicles that are either not visible on the screen or are sufficiently far from the camera that it is hard to tell if their motion is exactly in step with the world geometry. The PhysX vehicles SDK presents a number of options for reducing the computational load for vehicles that require only low levels of detail.</p> +<div class="section" id="extrapolation"> +<h4>Extrapolation<a class="headerlink" href="#extrapolation" title="Permalink to this headline">¶</a></h4> +<p>The most obvious strategy for a vehicle that requires only a low level of detail is simply to stop performing raycasts (PxVehicleSuspensionRaycasts) and updates (PxVehicleUpdates) for that vehicle. Instead of computing the ground underneath the vehicle's tires and computing the suspension and tire forces each and every frame it might be acceptable to avoid these steps completely and let the PhysX SDK update the rigid body with the legacy momentum of the rigid body. After several frames the vehicle's wheels will likely either be hovering above the ground or intersecting the ground so there needs to be a strategy to decide how many PhysX SDK updates can pass before the vehicle is once more updated properly by including it in the vehicles array passed to PxVehicleSuspensionRaycasts/PxVehicleUpdates. The details of any such strategy are left to users of the vehicles SDK because it depends on a number of factors such as distance from the camera; the spatial coherence of the world geometry near the vehicle; the speed of the vehicle; and whether the audio or graphics fx for the vehicle play an important role.</p> +</div> +<div class="section" id="disable-wheels"> +<h4>Disable Wheels<a class="headerlink" href="#disable-wheels" title="Permalink to this headline">¶</a></h4> +<p>If there exist vehicles with large wheel counts it might also be possible to reduce the number of wheels that participate in the simulation by calling PxVehicleWheelsSimData::disableWheel. An example might be a truck with 18 wheels. Now, such a truck will clearly need to perform 18 raycasts, 18 tire force calculations and 18 updates of wheel rotation speed in order to complete the vehicle update. If the truck can be reduced to just 4 enabled wheels then it is clear that less computational work is required. It is important to note that when wheels are disabled they no longer participate in supporting the mass of the vehicle's rigid body. In the extreme case of an 18-wheeled truck reduced to just 4 active wheels this will mean that the remaining enabled suspension springs are only configured to support approximately 4/18 of the mass of the vehicle's rigid body. To remedy this problem the mass of the rigid body will need to be re-distributed among the enabled wheels and suspensions, perhaps using PxVehicleComputeSprungMasses. A more complete description of the issues surrounding disabled wheels can be found in Section <a class="reference internal" href="#threewheeled"><em>3-Wheeled Cars</em></a>.</p> +</div> +<div class="section" id="swapping-multiple-vehicle-versions"> +<h4>Swapping Multiple Vehicle Versions<a class="headerlink" href="#swapping-multiple-vehicle-versions" title="Permalink to this headline">¶</a></h4> +<p>Instead of disabling wheels, perhaps a simpler and more effective way of reducing the computational cost is to instantiate two versions of the vehicle with different wheel +counts. The two vehicles can be easily swapped in the vehicles array passed to PxVehicleSuspensionRaycasts/PxVehicleUpdates as the required level of detail increases and +decreases. It is worth considering how this might work in the case of the 18-wheeled truck mentioned earlier. The simplest strategy would be to first construct the required +rigid body and attach a PxShape instance for each of the 18 wheels of the 18-wheeled truck. Instantiating the required 18-wheeled version of the truck with PxVehicleNW::create or PxVehicleNW::setup will automatically pose the shapes of all 18 wheels in the rest pose. The next step is to choose 4 of the 18 wheels to form the 4-wheeled version of the truck. Many choices are available but the most obvious choice would be the front-left/front-right/rear-left/rear-right wheels of the 18-wheeled truck. The 4-wheeled version can then be instantiated using the same rigid body as for the 18-wheeled version. This will pose 4 of the PxShape instances to the rest pose of the 4-wheeled truck. If the wheels of the 4-wheeled version have been set up correctly the rest poses ought to be identical to their counterparts in the 18-wheeled version. A key point to note is that both versions of the vehicle apply forces to the same rigid body. Another key point to note is that when the 4-wheeled vehicle is chosen only 4 of the 18 PxShape instances will have their pose updated, leaving 14 PxShape instances at either the rest local pose or the local pose given to them when the 18-wheeled version was last used. In terms of visible accuracy, these unposed shapes are the main disadvantage of the lower LOD vehicle. The differences in handling are much harder to gauge.</p> +<p>A number of useful functions are available to make it easy to swap between two or more versions of the same vehicle:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">PxVehicleComputeSprungMasses</span><span class="p">(</span><span class="k">const</span> <span class="n">PxU32</span> <span class="n">nbSprungMasses</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVec3</span><span class="o">*</span> <span class="n">sprungMassCoordinates</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxVec3</span><span class="o">&</span> <span class="n">centreOfMass</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxReal</span> <span class="n">totalMass</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxU32</span> <span class="n">gravityDirection</span><span class="p">,</span> <span class="n">PxReal</span><span class="o">*</span> <span class="n">sprungMasses</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">copy</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVehicleWheelsSimData</span><span class="o">&</span> <span class="n">src</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxU32</span> <span class="n">srcWheel</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxU32</span> <span class="n">trgWheel</span><span class="p">);</span> +<span class="kt">void</span> <span class="n">PxVehicleSuspensionData</span><span class="o">::</span><span class="n">setMassAndPreserveNaturalFrequency</span><span class="p">(</span><span class="k">const</span> <span class="n">PxReal</span> <span class="n">newSprungMass</span><span class="p">);</span> +<span class="kt">void</span> <span class="nf">PxVehicleCopyDynamicsData</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVehicleCopyDynamicsMap</span><span class="o">&</span> <span class="n">wheelMap</span><span class="p">,</span> + <span class="k">const</span> <span class="n">PxVehicleWheels</span><span class="o">&</span> <span class="n">src</span><span class="p">,</span> <span class="n">PxVehicleWheels</span><span class="o">*</span> <span class="n">trg</span><span class="p">);</span> +</pre></div> +</div> +<p>The following pseudo-code hopefully makes clear how to apply these functions in order to first construct the lower LOD vehicle and then swap between the different versions:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">PxVehicleDriveNW</span><span class="o">*</span> <span class="nf">instantiate4WVersion</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVehicleDriveNW</span><span class="o">&</span> <span class="n">vehicle18W</span><span class="p">,</span> <span class="n">PxPhysics</span><span class="o">&</span> <span class="n">physics</span><span class="p">)</span> +<span class="p">{</span> + <span class="c1">//Compute the sprung masses of the 4-wheeled version.</span> + <span class="n">PxReal</span> <span class="n">sprungMasses</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span> + <span class="p">{</span> + <span class="k">const</span> <span class="n">PxReal</span> <span class="n">rigidBodyMass</span> <span class="o">=</span> <span class="n">vehicle18W</span><span class="p">.</span><span class="n">getRigidDynamicActor</span><span class="p">()</span><span class="o">-></span><span class="n">getMass</span><span class="p">();</span> + <span class="k">const</span> <span class="n">PxVec3</span> <span class="n">wheelCoords</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> + <span class="p">{</span> + <span class="n">vehicle18W</span><span class="p">.</span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> + <span class="n">vehicle18W</span><span class="p">.</span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> + <span class="n">vehicle18W</span><span class="p">.</span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> + <span class="n">vehicle18W</span><span class="p">.</span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getWheelCentreOffset</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> + <span class="p">};</span> + <span class="k">const</span> <span class="n">PxU32</span> <span class="n">upDirection</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> + <span class="n">PxVehicleComputeSprungMasses</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="n">wheelCoords</span><span class="p">,</span> <span class="n">PxVec3</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="mi">0</span><span class="p">),</span> <span class="n">rigidBodyMass</span><span class="p">,</span> <span class="n">upDirection</span><span class="p">,</span> + <span class="n">sprungMasses</span><span class="p">);</span> + <span class="p">}</span> + + <span class="c1">//Set up the wheels simulation data.</span> + <span class="n">PxVehicleWheelsSimData</span><span class="o">*</span> <span class="n">wheelsSimData4W</span> <span class="o">=</span> <span class="n">PxVehicleWheelsSimData</span><span class="o">::</span><span class="n">allocate</span><span class="p">(</span><span class="mi">4</span><span class="p">);</span> + <span class="k">for</span><span class="p">(</span><span class="n">PxU32</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">4</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">wheelsSimData4W</span><span class="o">-></span><span class="n">copy</span><span class="p">(</span><span class="n">vehicle18W</span><span class="p">.</span><span class="n">mWheelsSimData</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span> + + <span class="n">PxVehicleSuspensionData</span> <span class="n">suspData</span> <span class="o">=</span> <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">getSuspensionData</span><span class="p">(</span><span class="n">i</span><span class="p">);</span> + <span class="n">suspData</span><span class="p">.</span><span class="n">setMassAndPreserveNaturalFrequency</span><span class="p">(</span><span class="n">sprungMasses</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> + <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">setSuspensionData</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">suspData</span><span class="p">);</span> + <span class="p">}</span> + <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">setTireLoadFilterData</span><span class="p">(</span><span class="n">vehicle18W</span><span class="p">.</span><span class="n">mWheelsSimData</span><span class="p">.</span><span class="n">getTireLoadFilterData</span><span class="p">());</span> + + <span class="c1">//Make sure the correct shapes are posed.</span> + <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">setWheelShapeMapping</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="n">wheelsSimData4W</span><span class="o">-></span><span class="n">setWheelShapeMapping</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span> + <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">setWheelShapeMapping</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span> + <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">setWheelShapeMapping</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span> + + <span class="c1">//Set up the drive simulation data.</span> + <span class="n">PxVehicleDriveSimDataNW</span> <span class="n">driveSimData4W</span> <span class="o">=</span> <span class="n">vehicle18W</span><span class="p">.</span><span class="n">mDriveSimData</span><span class="p">;</span> + <span class="n">PxVehicleDifferentialNWData</span> <span class="n">diff4W</span><span class="p">;</span> + <span class="n">diff4W</span><span class="p">.</span><span class="n">setDrivenWheel</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + <span class="n">diff4W</span><span class="p">.</span><span class="n">setDrivenWheel</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + <span class="n">diff4W</span><span class="p">.</span><span class="n">setDrivenWheel</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + <span class="n">diff4W</span><span class="p">.</span><span class="n">setDrivenWheel</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> + <span class="n">driveSimData4W</span><span class="p">.</span><span class="n">setDiffData</span><span class="p">(</span><span class="n">diff4W</span><span class="p">);</span> + + <span class="c1">//Instantiate the 4-wheeled version.</span> + <span class="n">PxRigidDynamic</span><span class="o">*</span> <span class="n">rigidDynamic</span> <span class="o">=</span> + <span class="k">const_cast</span><span class="o"><</span><span class="n">PxRigidDynamic</span><span class="o">*></span><span class="p">(</span><span class="n">vehicle18W</span><span class="p">.</span><span class="n">getRigidDynamicActor</span><span class="p">());</span> + <span class="n">PxVehicleDriveNW</span><span class="o">*</span> <span class="n">vehicle4W</span> <span class="o">=</span> + <span class="n">PxVehicleDriveNW</span><span class="o">::</span><span class="n">create</span><span class="p">(</span><span class="o">&</span><span class="n">physics</span><span class="p">,</span> <span class="n">rigidDynamic</span><span class="p">,</span> <span class="o">*</span><span class="n">wheelsSimData4W</span><span class="p">,</span> <span class="n">driveSimData4W</span><span class="p">,</span> <span class="mi">4</span><span class="p">);</span> + + <span class="c1">//Delete the wheels simulation data now that we have copied the data to the instantiated</span> + <span class="c1">//vehicle.</span> + <span class="n">wheelsSimData4W</span><span class="o">-></span><span class="n">free</span><span class="p">();</span> + + <span class="c1">//Finished.</span> + <span class="k">return</span> <span class="n">vehicle4W</span><span class="p">;</span> +<span class="p">}</span> + +<span class="kt">void</span> <span class="nf">swapToLowLodVersion</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVehicleDriveNW</span><span class="o">&</span> <span class="n">vehicle18W</span><span class="p">,</span> <span class="n">PxVehicleDrive4W</span><span class="o">*</span> <span class="n">vehicle4W</span><span class="p">,</span> + <span class="n">PxVehicleWheels</span><span class="o">**</span> <span class="n">vehicles</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">vehicleId</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">vehicles</span><span class="p">[</span><span class="n">vehicleId</span><span class="p">]</span> <span class="o">=</span> <span class="n">vehicle4W</span><span class="p">;</span> + + <span class="n">PxVehicleCopyDynamicsMap</span> <span class="n">wheelMap</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">=</span><span class="mi">2</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="o">=</span><span class="mi">3</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">=</span><span class="mi">2</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="o">=</span><span class="mi">3</span><span class="p">;</span> + + <span class="n">PxVehicleCopyDynamicsData</span><span class="p">(</span><span class="n">wheelMap</span><span class="p">,</span> <span class="n">vehicle18W</span><span class="p">,</span> <span class="n">vehicle4W</span><span class="p">);</span> +<span class="p">}</span> + +<span class="kt">void</span> <span class="nf">swapToHighLowVersion</span><span class="p">(</span><span class="k">const</span> <span class="n">PxVehicleDriveNW</span><span class="o">&</span> <span class="n">vehicle4W</span><span class="p">,</span> <span class="n">PxVehicleDrive4W</span><span class="o">*</span> <span class="n">vehicle18W</span><span class="p">,</span> + <span class="n">PxVehicleWheels</span><span class="o">**</span> <span class="n">vehicles</span><span class="p">,</span> <span class="n">PxU32</span> <span class="n">vehicleId</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">vehicles</span><span class="p">[</span><span class="n">vehicleId</span><span class="p">]</span> <span class="o">=</span> <span class="n">vehicle18W</span><span class="p">;</span> + + <span class="n">PxVehicleCopyDynamicsMap</span> <span class="n">wheelMap</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">=</span><span class="mi">2</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">sourceWheelIds</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="o">=</span><span class="mi">3</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</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">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">=</span><span class="mi">2</span><span class="p">;</span> + <span class="n">wheelMap</span><span class="p">.</span><span class="n">targetWheelIds</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="o">=</span><span class="mi">3</span><span class="p">;</span> + + <span class="n">PxVehicleCopyDynamicsData</span><span class="p">(</span><span class="n">wheelMap</span><span class="p">,</span> <span class="n">vehicle4W</span><span class="p">,</span> <span class="n">vehicle18W</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +</div> +<div class="section" id="disable-raycasts"> +<h4>Disable Raycasts<a class="headerlink" href="#disable-raycasts" title="Permalink to this headline">¶</a></h4> +<p>In some scenes it might be possible not to issue raycasts for each vehicle prior to each update. Depending on the geometry, this can lead to significant gains.</p> +<p>The PhysX vehicles SDK provides a simple mechanism to disable or enable raycasts per update and per vehicle by specifying an array of booleans as a function argument in PxVehicleSuspensionRaycasts. An alternative to disabling raycasts using the boolean array would be to alter the array of vehicles passed to PxVehicleSuspensionRaycasts so that some vehicles scheduled for update in PxVehicleUpdates do not participate in the batched raycast prior to the update. It is anticipated that using the boolean array will allow the same vehicle array to be passed to both the raycast and update functions, thereby allowing simpler vehicle management.</p> +<p>Vehicles that participate in the batched raycast automatically store raycast hit planes which are re-used each subsequent update until they are replaced by the hit planes of the next raycast. This means that it is not necessary to perform raycasts each update, especially if the vehicle is moving slowly or the vehicle is far from the camera or the vehicle remains on the same plane for several updates in a row. As the frequency of updates preceded by a raycast decreases, the accuracy of the cached hit planes also decreases, meaning that the likelihood of visibly poor wheel placement increases. The lack of accuracy in the cached hit planes means that some wheels might end up hovering or intersecting the ground if raycasts are not performed prior to each update. It is left to users of the SDK to develop their own strategy to decide whether a vehicle requires a fresh raycast or not.</p> +<p>If a raycast is not performed prior to an update then the vehicle will only be able to report a partial description of its interaction with the scene. For example, as a consequence of deletion the actor or shape or material hit by the last suspension raycast may no longer exist in the scene several updates later. For this reason, the vehicle reports NULL pointers for the shapes/actors/materials if a cached plane is used instead of the hit planes of a fresh raycast. The documentation for PxWheelQueryResult describes this in detail.</p> +<p>The first update of any vehicle requires that a raycast is performed prior to the update. If a raycast is not performed prior to the first update then the vehicle will not have been given an opportunity to cache its raycast hit planes. Further, after each call to setToRestState the vehicle also needs to perform a raycast prior to the next update. The reason for this is that setToRestState clears the cached hit planes, meaning that they need to be re-computed once more.</p> +</div> +<div class="section" id="use-the-clutch-in-estimate-mode"> +<h4>Use The Clutch in Estimate Mode<a class="headerlink" href="#use-the-clutch-in-estimate-mode" title="Permalink to this headline">¶</a></h4> +<p>The vehicle SDK implements a mathematical model for the clutch that has two optional modes of operational accuracy: eESTIMATE and eBEST_POSSIBLE. If eBEST_POSSIBLE is chosen the SDK attempts to accurately update wheel and engine rotation speeds from their coupling through the clutch. It is worth mentioning that the clutch model in PxVehicleDriveTank reduces to a particularly simple set of equations that have fast analytical solution. As a consequence, the vehicle SDK ignores the clutch accuracy model for tanks and instead always opts to compute the best possible solution. In the case of PxVehicle4W only marginal performance gains can be produced by switching to eESTIMATE because at most only 4 wheels can ever be coupled to the clutch. The real performance gains from the estimated solution are to be had with PxVehicleNW instances with high wheel count.</p> +<p>If eESTIMATE is chosen the quality of the estimate can be tuned with PxVehicleClutchData::mEstimateIterations. As the value of this variable increases the computational cost also increases and the estimated solution approaches the best possible solution. At particularly large values of mEstimateIterations the cost of the estimated solution might even exceed that of the best possible solution but without adding any precision. On the other hand, particularly low values such as 1 might result in weak or inaccurate coupling between the engine and wheels. This can be particularly noticeable after a gear change or at standing starts or when the brakes are aggressively applied. In such situations large angular velocity differences at the clutch result in large torques that require computational effort to resolve. A poor estimate might, for example, result in oscillating engine rotation speeds after a gear change instead of the expected smooth transitions. The magnitude of accuracy loss and its subsequent effect on vehicle behavior are very difficult to quantify and really need tested for each vehicle and scene.</p> +<p>It is recommended that eBEST_POSSIBLE is chosen for vehicles that require a high level of detail and that eESTIMATE is only chosen for vehicles that require lower levels of detail. Care must be taken when tuning PxVehicleClutchData::mEstimateIterations to ensure that the loss of accuracy is acceptable for the required level of detail. In many cases the lowest possible value of 1 will turn out to provide perfectly acceptable. Smooth and physically believable behavior, however, is only guaranteed if eBEST_POSSIBLE is adopted.</p> +</div> +</div> +<div class="section" id="wheel-contact-beyond-raycasts"> +<h3>Wheel Contact Beyond Raycasts<a class="headerlink" href="#wheel-contact-beyond-raycasts" title="Permalink to this headline">¶</a></h3> +<p>This Section describes the steps required to simulate wheel volumes with scene query sweeps and contact modification. Sample code can be found in SnippetVehicleContactMod.</p> +<p>Section <a class="reference internal" href="#algorithm"><em>Algorithm</em></a> described how scene query raycasts are used to compute vehicle suspension forces. Expanding on this theme, Section <a class="reference internal" href="#filtering"><em>Filtering</em></a> described how to use scene query and simulation filtering to categorise scene shapes as either drivable or non-drivable surfaces: drivable surfaces interact only with suspension raycasts, while non-drivable surfaces interact with wheels only through rigid body contact.</p> +<p>A variety of issues arise from the the system of raycasts and filtering described above. One problem is that it may be impractical to author every shape in the scene as being either drivable or non-drivable: it is easy to imagine a landscape modelled with a single mesh that is partially drivable and partially non-drivable. Another problem is that raycasts ignore the extent of the wheel in the lateral and longitudinal directions. This is illustrated in Figures 2a and 2b.</p> +<div class="figure align-center" id="figure-2a"> +<a class="reference internal image-reference" href="../_images/RaycastFail.png"><img alt="../_images/RaycastFail.png" src="../_images/RaycastFail.png" /></a> +<p class="caption">Figure 2a: The raycast ignores the overlap of the wheel's volume with the angled ground plane.</p> +</div> +<div class="figure align-center" id="figure-2b"> +<a class="reference internal image-reference" href="../_images/RaycastFail2.png"><img alt="../_images/RaycastFail2.png" src="../_images/RaycastFail2.png" /></a> +<p class="caption">Figure 2b: The wheel rolls towards a wall in Frame 1 and is immediately pushed up to the elevated surface in Frame 2.</p> +</div> +<p>The problem illustrated in Figure 2a can be solved by replacing raycasts with sweeps. Instead of performing a raycast along the suspension direction through the centre of the wheel, the shape representing the wheel is swept from its transform at maximum compression to its transform at maximum elongation. Sweeping a volume through the scene means that all possible contact planes are considered. This is illustrated in Figure 3.</p> +<div class="figure align-center" id="figure-3"> +<a class="reference internal image-reference" href="../_images/SweepFindsPlane.png"><img alt="../_images/SweepFindsPlane.png" src="../_images/SweepFindsPlane.png" /></a> +<p class="caption">Figure 3: Sweeps pick up all contact planes under the wheel.</p> +</div> +<p>In Figure 3, it is easy to see that there are multiple contact points under the wheel, each with a different normal. A decision needs to be made about which of these contacts to accept as the driving surface and which to ignore. In some scenarios it is sufficient just to take the first contact encountered by the sweep and ignore all others. For such cases it is recommended to issue a blocking sweep. PhysX supports two types of scene query: blocking and non-blocking. A detailed description of blocking and non-blocking queries can be found in Section <a class="reference internal" href="SceneQueries.html#queryfiltering"><em>Filtering</em></a>. In summary, however, a blocking sweep will return the first contact encountered by the swept volume, while non-blocking sweeps return all contacts encountered by the sweep. The scenario in Figure 3 suggests that a blocking sweep will be sufficient because it will return the inclined plane rather than the horizontal plane. As a consequence, the vehicle will start to drive on the inclined plane. Some scenarios, such as those depicted in Figure 2b, are more complex and require a non-blocking sweep.</p> +<div class="figure align-center" id="figure-4"> +<a class="reference internal image-reference" href="../_images/SweepPlusContact.png"><img alt="../_images/SweepPlusContact.png" src="../_images/SweepPlusContact.png" /></a> +<p class="caption">Figure 4: Judicious selection of sweep contacts and rigid body contacts is required to navigate a wheel through a complex scene.</p> +</div> +<p>Figure 4 shows a wheel rolling along a horizontal plane towards a vertical plane. The expected behavior is that the wheel continues to drive on the horizontal plane and is blocked by the vertical plane. It turns out that this can be readily achieved by judicious choice of sweep contacts and rigid body contacts. The first thing to note is that the sweep will return the three contact planes labelled A, B and C in Figure 4. If we have enabled rigid body contact between the wheel and the environment we will simultaneously have contact planes B and C as rigid body contacts. The next step is to devise a strategy that accepts contact plane B for the sweep and contact plane C for rigid body contact. This combination will ensure that the wheel bounces off the vertical plane and continues to drive on the lower horizontal plane. The strategy adopted by PhysX vehicles is to categorise sweep and rigid body contacts by comparing contact normals and points with the suspension direction. The aim is to divide contact with the environment into drivable contact planes and non-drivable contact planes. This can be achieved by introducing threshold angles to categories contact points and normals.</p> +<div class="figure align-center" id="figure-5"> +<a class="reference internal image-reference" href="../_images/ContactPointCategorisation.png"><img alt="../_images/ContactPointCategorisation.png" src="../_images/ContactPointCategorisation.png" /></a> +<p class="caption">Figure 5: The position of sweep and rigid body contact points relative to the suspension direction is used to filter the sweep and rigid body contacts. Sweep contacts in the light blue zone are accepted as driving planes, while rigid body contacts in the pink zone are accepted as rigid body contact planes.</p> +</div> +<div class="figure align-center" id="figure-6"> +<a class="reference internal image-reference" href="../_images/ContactNormalCategorisation.png"><img alt="../_images/ContactNormalCategorisation.png" src="../_images/ContactNormalCategorisation.png" /></a> +<p class="caption">Figure 6: The angle between contact normal and the suspension direction is used to categorised contact planes as either rigid body contacts or sweep contacts. Contact normals close to the suspension direction are accepted as driving planes, while normals far from the suspension direction are accepted as rigid body contact planes.</p> +</div> +<p>Figures 5 and 6 introduced two threshold angles that together allow sweep and rigid body contacts to be categorised using their position and normal. Having a numerical test for drivable and non-drivable contact points and normals allows a relaxation of the strict filtering rules described in Section <a class="reference internal" href="#filtering"><em>Filtering</em></a>. The idea now is to set up simulation filter data so that wheel shapes sweep against and collide with pretty much everything in the scene. The two threshold angles will filter and categorise sweep and rigid body contacts to generate the desired behavior.</p> +<p>The threshold angles shown in Figure 5 and Figure 6 are configured with the following function call:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">PxVehicleSetSweepHitRejectionAngles</span><span class="p">(</span><span class="k">const</span> <span class="n">PxF32</span> <span class="n">pointRejectAngle</span><span class="p">,</span> <span class="k">const</span> <span class="n">PxF32</span> <span class="n">normalRejectAngle</span><span class="p">);</span> +</pre></div> +</div> +<p>The code snippet SnippetVehicleContactMod demonstrates how to configure blocking and non-blocking sweeps. This snippet can be configured to run with either type of sweep by modifying the BLOCKING_SWEEPS define. Running the snippet with BLOCKING_SWEEPS demonstates that the situation depicted in Figure 4 requires non-blocking sweeps to ensure that the elevated horizontal plane is not chosen as the driving surface.</p> +<p>Suspension sweeps are issued with the following code:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//Suspension sweeps (instead of raycasts).</span> +<span class="c1">//Sweeps provide more information about the geometry under the wheel.</span> +<span class="n">PxVehicleWheels</span><span class="o">*</span> <span class="n">vehicles</span><span class="p">[</span><span class="n">NUM_VEHICLES</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="n">gVehicle4W</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">gVehicle4W</span><span class="p">[</span><span class="mi">1</span><span class="p">]};</span> +<span class="n">PxSweepQueryResult</span><span class="o">*</span> <span class="n">sweepResults</span> <span class="o">=</span> <span class="n">gVehicleSceneQueryData</span><span class="o">-></span><span class="n">getSweepQueryResultBuffer</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> +<span class="k">const</span> <span class="n">PxU32</span> <span class="n">sweepResultsSize</span> <span class="o">=</span> <span class="n">gVehicleSceneQueryData</span><span class="o">-></span><span class="n">getQueryResultBufferSize</span><span class="p">();</span> +<span class="n">PxVehicleSuspensionSweeps</span><span class="p">(</span><span class="n">gBatchQuery</span><span class="p">,</span> <span class="n">NUM_VEHICLES</span><span class="p">,</span> <span class="n">vehicles</span><span class="p">,</span> <span class="n">sweepResultsSize</span><span class="p">,</span> <span class="n">sweepResults</span><span class="p">,</span> <span class="n">gNbQueryHitsPerWheel</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="mf">1.0f</span><span class="p">,</span> <span class="mf">1.01f</span><span class="p">);</span> +</pre></div> +</div> +<p>In the event that non-blocking sweeps are implemented, the function PxVehicleUpdates rejects and accepts sweep hits using the threshold angles set in PxVehicleSetSweepHitRejectionAngles. When blocking sweeps are implemented only a single sweep contact is recorded. As a consequence, PxVehicleUpdates ignores the threshold angles and automatically works with the blocking sweep hit. The decision whether to use blocking or non-blocking sweeps is left to the developer because it depends on knowledge about the kinds of geometry that will be encountered by the vehicle. In some applications it will be sufficient to opt for the computationally cheaper option of blocking sweeps, while other applications may expect the vehicle to drive on complex geometry and are prepared to accept the extra cost of non-blocking sweeps.</p> +<p>Categorisation of rigid body contacts is implemented using contact modification callbacks. Contact modification is described in Section <a class="reference internal" href="AdvancedCollisionDetection.html#contact-modification"><em>Contact Modification</em></a>. The PhysX Vehicles SDK provides the function PxVehicleModifyWheelContacts to accept or reject contact points using the defined threshold angles. This function should be called from the contact modification callback, which is owned by the application. Configuration of contact modification callbacks involves a combination of simulation filter data and simulation shader. The implementation details, therefore, are left to application developers. SnippetVehicleContactMod illustrates one way to implement a contact modification callback using simulation filter data and the userdata pointers of PxShape and PxRigidDynamic. Other techniques are available using local knowledge in the application. In addition to adding sweeps and contact modification, the snippet also applies continuous collision detection (CCD) to the wheel shapes. CCD is introduced in Section <a class="reference internal" href="AdvancedCollisionDetection.html#continuous-collision-detection"><em>Continuous Collision Detection</em></a>.</p> +</div> +</div> +<div class="section" id="tuning-guide"> +<span id="id21"></span><h2>Tuning Guide<a class="headerlink" href="#tuning-guide" title="Permalink to this headline">¶</a></h2> +<p>This Sections describes the effect of the editable vehicle parameters of the data structures in PxVehicleComponents.h.</p> +<div class="section" id="pxvehiclewheeldata"> +<h3>PxVehicleWheelData<a class="headerlink" href="#pxvehiclewheeldata" title="Permalink to this headline">¶</a></h3> +<p>mRadius:</p> +<blockquote> +<div>This is the distance in metres between the center of the wheel and the outside rim of the tire. It is important that the value of the radius closely matches the radius of the render mesh of the wheel. Any mismatch will result in the wheels either hovering above the ground or intersecting the ground. Ideally, this parameter will be exported from the 3D modeler.</div></blockquote> +<p>mWidth:</p> +<blockquote> +<div>This is the full width of the wheel in metres. This parameter has no bearing on the handling but is a very useful parameter to have when trying to render debug data relating to the wheel/tire/suspension. Without this parameter it would be difficult to compute coordinates for render points and lines that ensure their visibility. Ideally, this parameter will be exported from the 3D modeler.</div></blockquote> +<p>mMass:</p> +<blockquote> +<div>This is the combined mass of the wheel and the tire in kg. Typically, a wheel has mass between 20Kg and 80Kg but can be lower and higher depending on the vehicle.</div></blockquote> +<p>mMOI:</p> +<blockquote> +<div><p>This is the component of the wheel's moment of inertia about the rolling axis. Larger values make it harder for the wheel to rotate about this axis, while lower values make it easier for the wheel to rotate about the rolling axis. Another way of expressing this is that a high MOI will result in less wheel spin when stamping on the accelerator because it is harder to make the wheel spin. Conversely, lower values of MOI will result in more wheel spin when stamping on the accelerator.</p> +<p>If the wheel is approximately cylindrical then a simple formula can be used to compute MOI:</p> +<blockquote> +<div>MOI = 0.5 * Mass * Radius * Radius</div></blockquote> +<p>There is no reason, however, to rely on equations to compute this value. A good strategy for tuning this number might to be start with the equation above and then make small tweaks to the value until the handling is as desired.</p> +</div></blockquote> +<p>mDampingRate:</p> +<blockquote> +<div>This value describes how quickly a freely spinning wheel will come to rest. The damping rate describes the rate at which a freely spinning wheel loses rotational speed. Here, a freely spinning wheel is one that experiences no forces except for the damping forces arising from the wheel's internal bearings. Higher damping rates result in the wheel coming to rest in shorter times, while lower damping rates result in the wheel maintaining speed for longer. Values in range (0.25, 2) seem like sensible values. Experimentation is always a good idea, even outside this range. Always exercise some caution with very small damping rates. In particular, a damping rate of exactly 0 should be avoided.</div></blockquote> +<p>mMaxBrakeTorque:</p> +<blockquote> +<div><p>This is the value of the torque applied to the wheel when the brakes are maximally applied. Higher torques will lock the wheel quicker when braking, while lower torques will take longer to lock the wheel. This value is strongly related to the wheel MOI because the MOI determines how quickly the wheel will react to applied torques.</p> +<p>A value of around 1500 is a good starting point for a vanilla wheel but a web search will reveal typical braking torques. One difficulty is that these are often expressed by manufacturers as braking horsepower or in "pounds inches". The values required here are in "Newton metres".</p> +</div></blockquote> +<p>mMaxHandBrakeTorque:</p> +<blockquote> +<div>This is the same as the max brake torque except for the handbrake rather than the brake. Typically, for a 4-wheeled car, the handbrake is stronger than the brake and is only applied to the rear wheels. A value of 4000 for the rear wheels is a good starting point, while a value of 0 is necessary for the front wheels to make sure they do not react to the handbrake.</div></blockquote> +<p>mMaxSteer:</p> +<blockquote> +<div>This is the value of the steer angle of the wheel (in radians) when the steering wheel is at full lock. Typically, for a 4-wheeled car, only the front wheels respond to steering. In this case, a value of 0 is required for the rear wheels. More exotic cars, however, might wish front and rear wheels to respond to steering. A value in radians equivalent to somewhere between 30 degrees and 90 degrees seems like a good starting point but it really depends on the vehicle being simulated. Larger values of max steer will result in tighter turns, while smaller values will result in wider turns. Be aware, though, that large steer angles at large speeds are likely to result in the car losing traction and spinning out of control, just as would happen with a real car. A good way to avoid this is to filter the steer angles passed to the car at run-time to generate smaller steer angles at larger speeds. This strategy will simulate the difficulty of achieving large steer angles at high speeds (at high speeds the wheels resist the turning forces applied by the steering wheel).</div></blockquote> +<p>mToeAngle:</p> +<blockquote> +<div><p>This is the angle of the wheel (in radians) that occurs with no steer applied. The toe angle can be used to help the car straighten up after coming out of a turn. This is a good number to experiment with but is best left at 0 unless detailed tweaks are required.</p> +<p>To help the car straighten up apply a small negative angle to one of the front wheels and a small positive angle to the other front wheel. By choosing which wheel takes the positive angles, and which the negative, it is straightforward to make the wheels either "toe-in" or "toe-out". A "toe-in" configuration, the front wheels pointing slightly towards each other, should help the car straighten up after a turn but at the expense of making it a little harder to turn in the first place. A "toe-out" configuration can have the opposite effect. Toe angles greater than a few degrees are best avoided.</p> +</div></blockquote> +</div> +<div class="section" id="pxvehiclewheelssimdata"> +<h3>PxVehicleWheelsSimData<a class="headerlink" href="#pxvehiclewheelssimdata" title="Permalink to this headline">¶</a></h3> +<p>void setSuspTravelDirection(const PxU32 id, const PxVec3& dir):</p> +<blockquote> +<div>This is the direction of the suspension in the downward direction in the rest configuration of the vehicle. A vector that points straight downwards is a good starting point.</div></blockquote> +<p>void setSuspForceAppPointOffset(const PxU32 id, const PxVec3& offset):</p> +<blockquote> +<div><p>This is the application point of the suspension force, expressed as an offset vector from the center of mass of the vehicle's rigid body. Another way of expressing this is to start at the center of mass of the rigid body, then move along the offset vector. The point at the end off the offset vector is the point at which suspension forces will be applied.</p> +<p>In a real vehicle the suspension forces are mediated through the suspension strut. These are often incredibly complex mechanical systems that are computationally expensive to simulate. As a consequence, instead of modeling the details of the suspension strut, it makes sense to assume that the suspension strut has an effective point at which it applies the force to the rigid body. Choosing that point, however, needs careful consideration. At the same time, it opens up all sorts of tweaking possibilities, freed from the constraints of the real world.</p> +<p>Deciding on the suspension force application point requires some thought. The suspension is very close to the wheel so the wheel center is a good starting point. Consider a line through the wheel center and along the suspension travel direction. Somewhere along this line seems like an even better idea for the application point, albeit not completely scientific. For a standard 4-wheeled car it makes sense that the application point is somewhere above the wheel center but below the center of mass of the rigid body. It is probably above the wheel center because the suspension is mostly above this point. It can be assumed that it is somewhere below the rigid body center of mass because otherwise vehicles would lean out of the turn rather than in to the turn. This narrows down the application point to really quite a small section of a known line.</p> +<p>When editing the suspension force application point it is important to bear in mind that lowering the app point too far will result in cars leaning more into the turn. This can have a negative effect on handling because the inner wheel can take so much load that the response saturates, while the outer wheel ends up with reduced load and reduced turning force. The result is poor cornering. Conversely, setting the app point too high will result in cornering that looks unnatural. The aim is to achieve a good balance.</p> +</div></blockquote> +<p>void setTireForceAppPointOffset(const PxU32 id, const PxVec3& offset):</p> +<blockquote> +<div>This is almost the same as the suspension force app point except for the lateral and longitudinal forces that develop on the tire. A good starting point is to duplicate the suspension force application point. Only for really detailed editing is it advised to start tweaking the tire force app offset independently of the suspension force app offset.</div></blockquote> +<p>void setWheelCentreOffset(const PxU32 id, const PxVec3& offset):</p> +<blockquote> +<div>This is the center of the wheel at rest position, expressed as an offset vector from the vehicle's center of mass.</div></blockquote> +</div> +<div class="section" id="pxvehiclesuspensiondata"> +<span id="vehicle-suspension"></span><h3>PxVehicleSuspensionData<a class="headerlink" href="#pxvehiclesuspensiondata" title="Permalink to this headline">¶</a></h3> +<p>mSprungMass:</p> +<blockquote> +<div><p>This is the mass in kg that is supported by the suspension spring.</p> +<p>A vehicle with rigid body center of mass at the center of the four wheels would typically be equally supported by each of the suspension springs; that is, each suspension spring supports 1/4 of the total vehicle mass. If the center of mass was moved forward then it would be expected that the front wheels would need to support more mass than the rear wheels. Conversely, a center of mass nearer the rear wheels ought to result in the rear suspension springs supporting more mass than at the front.</p> +<blockquote> +<div><div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">In order to achieve stability at the desired rest pose it is recommended that the collection of sprung masses matches the mass and center of mass of the rigid body. There are two strategies that can be employed to achieve this. The first approach is to decide upon values for the individual sprung masses and work forwards to compute an equivalent value for the rigid body mass and center of mass. More specifically, the rigid body mass and center of mass can be computed using the equations presented in Section <a class="reference internal" href="#algorithm"><em>Algorithm</em></a> and then applied to the vehicle's PxRigidDynamic instance. The second approach starts with the rigid body mass and center of mass of the vehicle's PxRigidDynamic instance and works backwards to compute and set the sprung masses. This makes use of the function PxVehicleComputeSprungMasses that was introduced in Section <a class="reference internal" href="#setupwheelssimulationdata"><em>setupWheelsSimulationData</em></a>.</p> +</div> +</div></blockquote> +</div></blockquote> +<p>mMaxCompression:</p> +<p>mMaxDroop:</p> +<blockquote> +<div><p>These values describe the maximum compression and elongation in metres that the spring can support. The total travel distance along the spring direction that is allowed is the sum of mMaxCompression and mMaxDroop.</p> +<p>A simple way to illustrate the maximum droop and compression values is to consider a car that is suspended in mid-air so that none of the wheels are touching the ground. The wheels will naturally fall downwards from their rest position until the maximum droop is reached. The spring cannot be elongated beyond this point. Now consider that the wheel is pushed upward, first to its rest position, then further pushed until the spring can no longer be compressed. The displacement from the rest position is the maximum compression of the spring.</p> +<p>It is important to choose the maximum compression value so that the wheel is never placed where the visual mesh of the wheel intersects the visual meshes of the car chassis. Ideally, these values will be exported from the 3d modeler.</p> +</div></blockquote> +<p>mSpringStrength:</p> +<blockquote> +<div><p>This value describes the strength of the suspension spring. The spring strength has a profound influence on handling by modulating the time it takes for the vehicle to respond to bumps in the road and on the amount of load experienced by the tire.</p> +<p>Key to understanding the effect of spring strength is the concept of a spring's natural frequency. Consider a simple spring system, such as a pendulum swinging back and forth. The number of trips per second that the pendulum makes from full left to full right and then back again is called the natural frequency of the pendulum. A more powerful pendulum spring will result in the pendulum swinging faster, thereby increasing the natural frequency. Conversely, increasing the pendulum mass will result in a slower oscillation, thereby reducing the natural frequency.</p> +<p>In the context of a suspension spring supporting a fixed portion of vehicle mass, the strength of the spring will affect the natural frequency; that is, the rate at which the spring can respond to changes in load distribution. Consider a car taking a corner. As the car corners it leans in to the turn, putting more weight on the suspensions on the outside of the turn. The speed at which the spring reacts by applying forces to redistribute the load is controlled by the natural frequency. Very high natural frequencies, such as those on a racing car, will naturally produce twitchy handling because the load on the tires, and therefore the forces they can generate, is varying very rapidly. Very low natural frequencies, on the other hand, will result in the car taking a long time to straighten up even after the turn is complete. This will produce sluggish and unresponsive handling.</p> +<p>Another effect of strength and and natural frequency is the response of a car to a bump in the road. High natural frequencies can result in the car responding very strongly and quickly to the bump, with the wheel possibly even leaving the road for a short while. This not only creates a bumpy ride but also periods of time when the tire is generating no forces. Weaker springs will result in a smoother trip over the bump, with weaker but more constant tire forces. A balance must be found to tune the car for the expected types of turn and terrain.</p> +<p>The natural frequency of the spring presents a challenge for computer simulation. A smooth and stable simulation requires that the spring is updated at a frequency much greater than the spring's natural frequency. An alternative way of expressing this is to consider the period of the spring relative to the timestep of the simulation. The period of the spring is the time the spring takes to complete a single oscillation, and is mathematically equal to the reciprocal of the natural frequency. In order to achieve a stable simulation the spring must be sampled at several points during each oscillation. A natural consequence of this observation is that the simulation timestep must be significantly smaller than the period of the spring. To discuss this further it is helpful to introduce a ratio that describes the number of simulation updates that will occur during each spring oscillation. This ratio is simply the spring period divided by the timestep</p> +<blockquote> +<div>alpha = sqrt(mSprungMass/mSpringStrength)/timestep</div></blockquote> +<p>where sqrt(mSprungMass/mSpringStrength) is the period of the spring. An alpha value of 1.0 means that the chosen timestep and spring properties only allow a single sample of the spring during each oscillation. As described above, this is almost guaranteed to produce unstable behavior. In fact, the argument presented so far suggests a value of alpha significantly greater than 1.0 is essential to produce a smooth simulation. The exact value of alpha at which stability emerges is very difficult to predict and depends on many other parameters. As a guide, however, it is recommended that the timestep and spring properties are chosen so that they produce an alpha value greater than 5.0; that is, a minimum of five simulation updates per spring cycle.</p> +<p>When tuning a suspension spring it can be very useful to use manufacturer data to discover typical values used across a range of vehicle types. This data is not always readily available. An alternative strategy would be to think in terms of the natural frequency of the spring by imagining how quickly the car would oscillate up and down if it was dropped onto the ground from a height of, say, 0.5m. The springs of a typical family car have natural frequency somewhere between 5 and 10; that is, such a car would make 5-10 oscillations per second if gently dropped to the ground. If the mass supported by the spring is already known then the spring strength can be calculated from the following equation</p> +<blockquote> +<div><p>mSpringStrength = naturalFrequency * naturalFrequency * mSprungMass</p> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">To achieve a spring that is theoretically correct, the values for mSprungMass, mSpringStrength and mMaxDroop should be chosen so that they obey the equation mSpringStrength*mMaxDroop = mSprungMass*gravitationalAcceleration. When this equation is satisfied the spring is guaranteed to provide exactly zero force at maximum elongation and also to support the sprung mass at the rest pose (the rest pose is defined by PxVehicleWheelsSimDta::setWheelCentreOffset). It is often the case, however, that the visual requirements of the car are in conflict with its handling requirements. An example might be a visual requirement, imposed by an artist, on both the rest pose and the suspension travel limits. In order to satisfy this visual requirement and achieve a theoretically correct spring, the value of mSpringStrength must be equivalent to mSprungMass*gravitationalAcceleration/mMaxDroop. If this value of mSpringStrength does not meet the handling requirements of the game then there is a conflict that cannot be easily resolved. For this reason, the PhysX Vehicles module does not require the spring to be a theoretically perfect spring. The consequences of an imperfect spring are that the spring either stops providing upward force before it hits maximum elongation or that it still provides a non-zero force at maximum elongation. The effect on handling or on the visual appearance of the vehicle is often quite difficult to spot. In particular, tire load filtering, discussed in Section <a class="reference internal" href="#pxvehicletireloadfilterdata"><em>PxVehicleTireLoadFilterData</em></a>, further disguises any imperfection.</p> +</div> +</div></blockquote> +</div></blockquote> +<p>mSpringDamperRate:</p> +<blockquote> +<div><p>This describes the rate at which the spring dissipates the energy stored in the spring.</p> +<p>Key to the understanding of damper rate are the concepts of under-damping, over-damping, and critical damping. An over-damped pendulum displaced from rest is unable to make a single back-and-forth trip before it dissipates all its energy, while an under-damped pendulum would be able to make at least a single back-and-forth trip. A critically damped pendulum makes exactly a single back-and-forth trip before expending all its energy.</p> +<p>For vehicle suspension springs, it is typically important to make sure that the spring has a damper rate that produces over-damping but not by too much. When cornering, for example, it is important that the spring doesn't over-respond by shifting the weight from the left suspension to the right suspension then back again. If this happened the tire load, and the forces generated, would be extremely variable, resulting in twitchy and uncontrollable handling. A very heavily over-damped spring, on the other hand, will feel sluggish and unresponsive.</p> +<p>The concept of critical damping can be used to help tune the damping rate of the spring. It is helpful to introduce a value known as the damping ratio, which helps to mathematically describe the under-damping, critical damping and over-damping regimes.</p> +<blockquote> +<div>dampingRatio = mSpringDamperRate/[2 * sqrt(mSpringStrength * mSprungMass)]</div></blockquote> +<p>A dampingRatio with value greater than 1.0 produces over-damping, a value of exactly 1.0 generates critical damping, and a value less than 1.0 is under-damped. It can be useful to first think about whether the spring will be under-damped or over-damped, then think about how far it will be from critical damping. This process allows a number to be subjectively applied to the damping ratio. From here the damping rate can be directly computed by rearranging the equation above</p> +<blockquote> +<div>mSpringDamperRate = dampingRatio * 2 * sqrt(mSpringStrength * mSprungMass)</div></blockquote> +<p>A typical family car is probably slightly over-damped, having dampingRatio with value perhaps just over 1.0. A guideline would be that values very far from critical damping are likely to be unrealistic and will either produce sluggish or twitchy handling. It is difficult to put an exact figure on this but somewhere between 0.8 and 1.2 seems like a good starting point for the damping ratio.</p> +</div></blockquote> +<p>mCamberAtRest:</p> +<p>mCamberAtMaxCompression:</p> +<p>mCamberAtMaxDroop:</p> +<blockquote> +<div><p>These values describe the camber angle of the wheels as a function of suspension spring compression. It is typical for the wheels of extended springs to camber inward; that is, the left and right wheels almost seem to form the edges of a V shape when viewed from the front or rear along the forward axis of the vehicle. Compressed springs, on the other hand, typically camber outwards; that is, they almost form the outer edges of an A shape when when viewed from the front or rear along the forward axis of the vehicle.</p> +<p>These three values allow the camber angle to be computed for any value of spring compression using simple linear interpolation. At rest, when the spring is neither elongated or compressed, the camber angle is equal to mCamberAtRest. When the spring is compressed the camber is computed as a linear interpolation between mCamberAtRest and mCamberAtMaxCompression. When the spring is elongated the camber is computed as a linear interpolation between mCamberAtRest and mCamberAtMaxDroop.</p> +<p>The camber angle is used by the default tire model and is passed as a function argument to the tire shader. It is also used to set the local pose of the PxShape that geometrically represents the wheel.</p> +</div></blockquote> +</div> +<div class="section" id="pxvehicleantirollbar"> +<h3>PxVehicleAntiRollBar<a class="headerlink" href="#pxvehicleantirollbar" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>When a vehicle takes a corner the turning force causes the car to roll. Typically, the suspension springs on the outside of the turn are compressed while the suspension springs on the inside of the turn are elongated. If the roll is so severe that the inside wheels completely leave the ground then there is a danger that the driver will lose control of the vehicle. In such cases, there is even a danger that the vehicle will rotate onto its side. For less severe rolls there still remains a handling problem that arises from the distribution of load between the inside and outside tires. The issue here is that the imbalance of the vehicle can lead to under-steer or over-steer.</p> +<p>Anti-roll bars are commonly used to reduce the roll that naturally occurs when cornering. They typically work as a torsion spring that applies a torque in order to minimise the difference in spring displacement for a pair of wheels. A standard family car might feature a front and rear anti-roll bar. The front bar applies a torque to reduce the difference between the front-left and front-right wheels. Similarly, the rear bar applies a torque to reduce the difference between the rear-left and rear-right wheels.</p> +<p>The magnitude of the anti-roll torque is proportional to the difference in spring displacement of the two wheels that are connected by the bar. The magnitude is also proportional to a stiffness parameter: stiffer bars generate more anti-roll torque.</p> +<p>As a general rule, under-steer can be reduced by increasing the stiffness of the rear anti-roll bar. Increasing the stiffness of the front anti-roll bar typically reduces over-steer.</p> +<p>mWheel0: +mWheel1:</p> +<blockquote> +<div>The anti-roll bar connects two wheels described by the indices mWheel0 and mWheel1.</div></blockquote> +<p>mStiffness:</p> +<blockquote> +<div>This parameter describes the stiffness of the anti-roll bar.</div></blockquote> +</div></blockquote> +</div> +<div class="section" id="pxvehicletiredata"> +<h3>PxVehicleTireData<a class="headerlink" href="#pxvehicletiredata" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>The tire force computation is performed in two conceptual stages. The first stage of the computation independently computes the lateral and longitudinal components of the force using linear equations. These independent forces are computed by treating the tire as a linear system so that the force in each direction can be theoretically viewed as the product of a tire strength per unit slip and the slippage experienced by the tire. The second stage of the computation applies the rule that the combined tire force is limited by the product of the tire load and friction. Just as with rigid bodies, tires are able to resist greater horizontal forces when they experience a large normal load on a surface with high friction value. With this in mind the maximum resistance force for a tire can be approximated as the product of the normal load and the friction value. The default PhysX Vehicle tire model employs a series of smoothing functions to implement the normalization of the combined tire forces.</p> +<p>In addition to the lateral and longitudinal components of force a camber thrust force, arising from the camber angle of the tire, is also computed. Typically, this provides only a small correction to the effect of the lateral and longitudinal components. The camber force participates in the normalization process.</p> +<p>The following tire parameters describe the computation of the independent lateral and longitudinal and camber components; that is, the first conceptual stage of the force computation. Reference is made throughout to the handling consequences of the normalization process.</p> +</div></blockquote> +<p>mLongitudinalStiffnessPerUnitGravity:</p> +<blockquote> +<div><p>The longitudinal stiffness describes the longitudinal forces that develop per unit of longitudinal slip (in radians). Here, a variable that represents the longitudinal stiffness per unit gravity has been introduced in order to make the variable robust against any edits to the value of gravitational acceleration. The longitudinal tire force is approximately the product of the longitudinal stiffness per unit gravity and the longitudinal slip and the magnitude of gravitational acceleration:</p> +<blockquote> +<div>longitudinalTireForce = mLongitudinalStiffnessPerUnitGravity * longitudinalSlip * gravity;</div></blockquote> +<p>Increasing this value will result in the tire attempting to generate more longitudinal force when the tire is slipping. Typically, increasing longitudinal stiffness will help the car accelerate and brake. The total tire force available is limited by the load on the tire so be aware that increases in this value might have no effect or even come at the expense of reduced lateral force.</p> +</div></blockquote> +<p>mLatStiffX:</p> +<p>mLatStiffY:</p> +<blockquote> +<div><p>These values together describe the lateral stiffness per unit lateral slip (in radians) of the tire. The lateral stiffness of a tire has a role similar to the longitudinal stiffness (mLongitudinalStiffnessPerUnitGravity), except that it governs the development of lateral tire forces, and is a function of tire load. Typically, increasing lateral stiffness will help the car turn more quickly. The total tire force available is limited by the load on the tire so be aware that increases in this value might have no effect or even come at the expense of reduced longitudinal force.</p> +<p>Lateral stiffness is a little more complicated than longitudinal stiffness because tires typically provide poor response under heavy load. Typical for car tires is a graph of lateral force against load that has linear response close to zero load but saturates at greater loads. This means that at low tire loads the lateral stiffness has a linear response to load; that is, more load results in more stiffness and more lateral(turning) force. At higher tire loads the tire has a saturated response and is in a regime where applying more load will not result in more tire stiffness. In this latter regime it would be expected that the tire would start slipping.</p> +<p>The combination of two values mLatStiffX and mLatStiffY describe a graph of lateral stiffness per unit load as a function of normalized tire load. The tire force computation employs a smoothing function which requires knowledge of the normalized tire load at which the tire has a saturated response to tire load along with the lateral stiffness per unit load that occurs at this saturation point. A typical curve can be seen in the graph below.</p> +<p>The parameter mLatStiffX describes the normalized tire load above which the tire has a saturated response to tire load. The normalized tire load is simply the tire load divided by the load that is experienced when the vehicle is perfectly at rest. A value of 2 for mLatStiffX, for example, means that when the the tire has a load more than twice its rest load it can deliver no more lateral stiffness no matter how much extra load is applied to the tire. In the graph below mLatStiffX has value 3.</p> +<p>The parameter mLatStiffY describes the maximum stiffness per unit of lateral slip (in radians) per unit rest load. The maximum stiffness is delivered when the tire is in the saturated load regime, governed in turn by mLatStiffX. In the graph below mLatStiffY has value 18.</p> +<p>The computation of the lateral stiffness begins by computing the load on the tire and then computing the normalized load in order to compute the number of rest loads experienced by the tire. This places the tire somewhere along the X-axis of the graph below. The corresponding value on the Y-axis of the curve parameterized by mLatStiffX and mLatStiffY is queried to provide the lateral stiffness per unit rest load. The final value for the lateral stiffness is then computed by multiplying the queried graph value by the rest load. This final value describes the lateral stiffness per unit lateral slip.</p> +<img alt="../_images/LatStiff.png" src="../_images/LatStiff.png" /> +<p>A good starting value for mLatStiffX is somewhere between 2 and 3. A good starting value for mLatStiffY is around 18 or so.</p> +</div></blockquote> +<p>mFrictionVsSlipGraph:</p> +<blockquote> +<div><blockquote> +<div><p>These six values describe a graph of friction as a function of longitudinal slip. Vehicle tires have a complicated response to longitudinal slip. This graph attempts to approximate this relationship.</p> +<p>Typically, tires have a linear response at small slips. This means that when the tire is only slightly slipping it is able to generate a response force that grows as the slip increases. At greater values of slip, the force can actually start to decrease from the peak value that occurs at the optimum slip. Beyond the optimum slip the tire eventually starts behaving less and less efficiently and hits a plateau of inefficiency.</p> +<p>The friction value for the combination of surface type and tire type has already been discussed in Section <a class="reference internal" href="#tire-friction-on-drivable-surfaces"><em>Tire Friction on Drivable Surfaces</em></a>. The graph of friction versus longitudinal slip is used as a correction to the combination friction value. In particular, a final friction value is computed from the product of the combination friction value and the graph's correction value. The tire model then responds to the final friction value.</p> +<p>The first two values describe the friction at zero tire slip: mFrictionVsSlipGraph[0][0] = 0, and mFrictionVsSlipGraph[0][1] = friction at zero slip.</p> +<p>The next two values describe the optimum slip and the friction at the optimum slip: mFrictionVsSlipGraph[1][0] = optimum slip, mFrictionVsSlipGraph[1][1] = friction at optimum slip.</p> +<p>The last two values describe the slip at which the plateau of inefficiency begins and the value of the friction available at the plateau of inefficiency: mFrictionVsSlipGraph[2][0] = slip at the start of the plateau of inefficiency, mFrictionVsSlipGraph[2][1] = the friction available at the plateau of inefficiency.</p> +<p>In the graph below the following values have been used:</p> +<p>mFrictionVsSlipGraph[0][0] = 0.0</p> +<p>mFrictionVsSlipGraph[0][1] = 0.4</p> +<p>mFrictionVsSlipGraph[1][0] = 0.5</p> +<p>mFrictionVsSlipGraph[1][1] = 1.0</p> +<p>mFrictionVsSlipGraph[2][0] = 0.75</p> +<p>mFrictionVsSlipGraph[2][1] = 0.60</p> +</div></blockquote> +<img alt="../_images/FrictionVsSlip.png" src="../_images/FrictionVsSlip.png" /> +<p>The friction values described here are used to scale the friction of the ground surface. This means they should be in range (0,1) but this is not a strict requirement. Typically, the friction from the graph would be close to 1.0 in order to provide a small correction to the ground surface friction.</p> +<p>A good starting point for this is a flat graph of friction vs slip with these values:</p> +<blockquote> +<div><p>mFrictionVsSlipGraph[0][0]=0.0</p> +<p>mFrictionVsSlipGraph[0][1]=1.0</p> +<p>mFrictionVsSlipGraph[1][0]=0.5</p> +<p>mFrictionVsSlipGraph[1][1]=1.0</p> +<p>mFrictionVsSlipGraph[2][0]=1.0</p> +<p>mFrictionVsSlipGraph[2][1]=1.0</p> +</div></blockquote> +</div></blockquote> +<p>mCamberStiffnessPerUnitGravity:</p> +<blockquote> +<div><p>The camber stiffness is analogous to the longitudinal and lateral stiffness, except that it describes the camber thrust force arising per unit camber angle (in radians). Similar to the longitudinal stiffness, a camber stiffness per unit gravity has been introduced to make the camber stiffness robust across different values of gravitational acceleration. The independent camber force is computed as the camber angle multiplied by the camber stiffness multiplied by the gravitational acceleration:</p> +<blockquote> +<div>camberTireForce = mCamberStiffnessPerUnitGravity * camberAngle * gravity;</div></blockquote> +</div></blockquote> +<p>mType:</p> +<blockquote> +<div>This parameter has been explained in Section <a class="reference internal" href="#tire-friction-on-drivable-surfaces"><em>Tire Friction on Drivable Surfaces</em></a>.</div></blockquote> +</div> +<div class="section" id="pxvehicleenginedata"> +<h3>PxVehicleEngineData<a class="headerlink" href="#pxvehicleenginedata" title="Permalink to this headline">¶</a></h3> +<p>mMOI:</p> +<blockquote> +<div>This the moment of inertia of the engine around the axis of rotation. Larger values make it harder to accelerate the engine, while lower values make it easier to accelerate the engine. A starting value of 1.0 is a good choice.</div></blockquote> +<p>mPeakTorque:</p> +<blockquote> +<div>This is the maximum torque that is ever available from the engine. This is expressed in Newton metres. A starting value might be around 600.</div></blockquote> +<p>mMaxOmega:</p> +<blockquote> +<div>This is the maximum rotational speed of the engine expressed in radians per second.</div></blockquote> +<p>mDampingRateFullThrottle:</p> +<p>mDampingRateZeroThrottleClutchEngaged:</p> +<p>mDampingRateZeroThrottleClutchDisengaged:</p> +<blockquote> +<div><p>These three values are used to compute the damping rate that is applied to the engine. If the clutch is engaged then the damping rate is an interpolation between mDampingRateFullThrottle and mDampingRateZeroThrottleClutchEngaged, where the interpolation is governed by the acceleration control value generated by the gamepad or keyboard. At full throttle mDampingRateFullThrottle is applied, while mDampingRateZeroThrottleClutchEngaged is applied at zero throttle. In neutral gear the damping rate is an interpolation between mDampingRateFullThrottle and mDampingRateZeroThrottleClutchDisengaged.</p> +<p>The three values allow a range of effects to be generated: good acceleration that isn't hampered by strong damping forces, tunable damping forces when temporarily in neutral gear during a gear change, and strong damping forces that will bring the vehicle quickly to rest when it is no longer being driven by the player.</p> +<p>Typical values in range (0.25,3). The simulation can become unstable with damping rates of 0.</p> +</div></blockquote> +<p>mTorqueCurve:</p> +<blockquote> +<div><p>This is a graph of peak torque versus engine rotational speed. Cars typically have a range of engine speeds that produce good drive torques, and other ranges of engine speed that produce poor torques. A skilled driver will make good use of the gears to ensure that the car remains in the "good" range where the engine is most responsive. Tuning this graph can have profound effects on gameplay.</p> +<p>The x-axis of the curve is the normalized engine speed; that is, the engine speed divided by the maximum engine speed. The y-axis of the curve is a multiplier in range (0,1) that is used to scale the peak torque.</p> +</div></blockquote> +</div> +<div class="section" id="pxvehiclegearsdata"> +<h3>PxVehicleGearsData<a class="headerlink" href="#pxvehiclegearsdata" title="Permalink to this headline">¶</a></h3> +<p>mNumRatios:</p> +<blockquote> +<div>This is the number of the gears of the vehicle, including reverse and neutral. A standard car with 5 forward gears would, therefore, have a value of 7 after accounting for reverse and neutral.</div></blockquote> +<p>mRatios:</p> +<blockquote> +<div>Each gear requires a gearing ratio. Higher gear ratios result in more torque but lower top speed in that gear. Typically, the higher the gear, the lower the gear ratio. Neutral gear must always be given a value of 0, while reverse gear must have a negative gear ratio. Typical values might be 4 for first gear and 1.1 for fifth gear.</div></blockquote> +<p>mFinalRatio:</p> +<blockquote> +<div>The gear ratio used in the simulator is the gear ratio of the current gear multiplied by the final ratio. The final ratio is a quick and rough way of changing the gearing of a car without having to edit each individual entry. Further, quoted gearing values from manufacturers typically mention ratios for each gear along with a final ratio. A typical value might be around 4.</div></blockquote> +<p>mSwitchTime:</p> +<blockquote> +<div><p>The switch time describes how long it takes (in seconds) for a gear change to be completed. It is impossible to change gear immediately in a real car. Manual gears, for example, require neutral to be engaged for a short time before engaging the desired target gear. While the gear change is being completed the car will be in neutral. A good trick might be to penalize players that use an automatic gear box by increasing the gear switch time.</p> +<p>If the autobox is enabled it is a good idea to set this value significantly lower than PxVehicleAutoBoxData::setLatency. If the autobox latency is smaller than the gear switch time then the autobox might decide to initiate a downwards gear change immediately after an upward gear shift has been completed. This situation can leave the car cycling between neutral and first gear with very short interludes in 2nd gear.</p> +</div></blockquote> +</div> +<div class="section" id="pxvehicleautoboxdata"> +<h3>PxVehicleAutoBoxData<a class="headerlink" href="#pxvehicleautoboxdata" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>The autobox initiates gear changes up or down based on the rotation speed of the engine. If the engine is rotating faster than a threshold value stored in PxVehicleAutoBoxData then a gear increment will be initiated. On the other hand, if the engine is rotating slower than a threshold value then the autobox will initiate a gear decrement. The autobox only initiates gear changes upward or downwards a single gear at a time.</p> +<p>It is worth noting that if the autobox initiates a gear change then the accelerator pedal is automatically disconnected from the engine for the entire duration of the gear change. Manual gear changes (PxVehicleDriveDynData::startGearChange / PxVehicleDriveDynData::mGearUpPressed / PxVehicleDriveDynData::mGearDownPressed) are not subject to this limitation. This is in keeping with typical real-world autobox behavior. The idea behind this is to stop the engine wildly accelerating during the neutral phase of the gear change, thereby avoiding damaging clutch slip when the clutch re-engages at the end of the gear change.</p> +<p>The autobox will not try to initiate a gear change while an automatic or manual gear change is still active.</p> +<p>If the autobox is too simplistic for the application's requirements then PxVehicleGearsData can be readily disabled. The choices following this are either to revert to a manual gear model or to implement a custom autobox in the application. A transition to a specific gear can be initiated with PxVehicleDriveDynData::startGearChange, while single gear changes can be initiated with PxVehicleDriveDynData::mGearUpPressed / PxVehicleDriveDynData::mGearDownPressed.</p> +<p>The autobox can be enabled or disabled by toggling PxVehicleDriveDynData::mUseAutoGears.</p> +</div></blockquote> +<p>PxReal mUpRatios[PxVehicleGearsData::eGEARSRATIO_COUNT]:</p> +<blockquote> +<div><p>The autobox will initiate a gear increment if the ratio of the engine rotation speed to the maximum allowed engine rotation speed:</p> +<blockquote> +<div>PxVehicleDriveDynData::getEngineRotationSpeed() / PxVehicleEngineData::mMaxOmega</div></blockquote> +<p>is greater than the value stored in mUpRatios[PxVehicleDriveDynData::getCurrentGear()]</p> +</div></blockquote> +<p>PxReal mDownRatios[PxVehicleGearsData::eGEARSRATIO_COUNT]:</p> +<blockquote> +<div><p>The autobox will initiate a gear decrement if the ratio of the engine rotation speed to the maximum allowed engine rotation speed:</p> +<blockquote> +<div>PxVehicleDriveDynData::getEngineRotationSpeed() / PxVehicleEngineData::mMaxOmega</div></blockquote> +<p>is less than the value stored in mUpRatios[PxVehicleDriveDynData::getCurrentGear()]</p> +</div></blockquote> +<p>void setLatency(const PxReal latency):</p> +<blockquote> +<div>After the autobox has initiated a gear change it will not attempt to initiate another gear change until the latency time has passed. It is a good idea to set this value significantly higher than PxVehicleGearsData::mSwitchTime. If the latency is smaller than the gear switch time then the autobox might decide to initiate a downwards gear change immediately after an upward gear shift has been completed. This situation can leave the car cycling between neutral and first gear with very short interludes in 2nd gear.</div></blockquote> +</div> +<div class="section" id="pxvehicleclutchdata"> +<h3>PxVehicleClutchData<a class="headerlink" href="#pxvehicleclutchdata" title="Permalink to this headline">¶</a></h3> +<p>mStrength:</p> +<blockquote> +<div><p>This describes how strongly the clutch couples the engine to the wheels and how quickly differences in speed are eliminated by distributing torque to the engine and wheels.</p> +<p>Weaker values will result in more clutch slip, especially after changing gear or stamping on the accelerator. Stronger values will result in reduced clutch slip, and more engine torque delivered to the wheels.</p> +<p>This value is to be edited only for very fine tweaking of the vehicle. Some clutch slip can be attributed to the numerical issues in the simulation at large timesteps, while some is a natural consequence of driving the car in an overly aggressive manner. A value of 10 is a good starting point.</p> +</div></blockquote> +</div> +<div class="section" id="pxvehicleackermanngeometrydata"> +<h3>PxVehicleAckermannGeometryData<a class="headerlink" href="#pxvehicleackermanngeometrydata" title="Permalink to this headline">¶</a></h3> +<p>mAccuracy:</p> +<blockquote> +<div>Ackermann correction allows better cornering by steering the left and right wheels with slightly different steer angles, as computed from simple trigonometry. In practice, it is impossible to engineer a steering linkage that will achieve the perfect Ackermann steering correction. This value allows the accuracy of the Ackermann steering correction to be controlled. Choosing a value of 0 completely disables Ackermann steer correction. A value of 1.0, on the other hand, achieves the impossible dream of perfect Ackermann correction.</div></blockquote> +<p>mFrontWidth:</p> +<blockquote> +<div>This is the distance in metres between the two front wheels.</div></blockquote> +<p>mRearWidth:</p> +<blockquote> +<div>This is the distance in metres between the two rear wheels.</div></blockquote> +<p>mAxleSeparation:</p> +<blockquote> +<div>This is the distance in metres between the center of the front axle and the center of the rear axle.</div></blockquote> +</div> +<div class="section" id="pxvehicletireloadfilterdata"> +<span id="id22"></span><h3>PxVehicleTireLoadFilterData<a class="headerlink" href="#pxvehicletireloadfilterdata" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>This is for very fine control of the handling, and corrects numerical issues inherent in simulations at large timesteps.</p> +<p>At large simulation timesteps the amplitude of motion of the suspension springs is larger than it would be in real-life. This is unfortunately unavoidable. On a bumpy surface this could mean that the simulation lifts the car further from the ground than would really happen. This could be quickly followed by the spring being more compressed than would be experienced with a real vehicle. A consequence of this oscillation is that the load on the tire is more variable than expected, and the available tire forces have more variability than expected. This filter aims to correct this numerical problem by smoothing the tire load with the aim of making the handling smoother and more predictable.</p> +<p>A key concept is that of normalized tire loads. A normalized tire load is just the actual load divided by the load experienced when the vehicle is in its rest configuration. If a tire experiences more load than it does at rest then it has a normalized tire load greater than 1.0. Similarly, if a tire has less load than it does at rest then it has a normalized tire load less than 1.0. At rest, all tires obviously have a normalized tire load of exactly 1.0. The normalized tire load can never be less than zero.</p> +<p>The values here describe points on a 2d graph that generates filtered tire loads from raw tire loads. The x-axis of the graph is "normalized tire load", while the y-axis of the graph is "filtered normalized tire load". Normalized loads less than mMinNormalisedLoad produce a filtered normalized load of mMinFilteredNormalisedLoad. Normalized loads greater than mMaxNormalisedLoad produce a filtered normalized load of mMaxFilteredNormalisedLoad. Loads in-between mMinNormalisedLoad and mMaxNormalisedLoad produce a filtered normalized load in-between mMinFilteredNormalisedLoad and mMaxFilteredNormalisedLoad, as computed by direct interpolation.</p> +<blockquote> +<div><img alt="../_images/FilteredLoad.png" src="../_images/FilteredLoad.png" /> +<p>Choosing mMaxNormalisedLoad and mMaxFilteredNormalisedLoad limits the maximum load that will ever be used in the simulation. On the other hand, choosing mMinFilteredNormalisedLoad>0 and/or mMinNormalisedLoad>0 allows the tire to potentially generate a non-zero tire force even when the tire is just touching the ground at maximum droop.</p> +<p>The filtered load can be made identical to the computed tire load by setting:</p> +<blockquote> +<div>mMinNormalisedLoad=mMaxFilteredNormalisedLoad=0 +mMaxNormalisedLoad=mMaxFilteredNormalisedLoad=1000.</div></blockquote> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Tires may only generate forces if the tire is touching the ground: if the tire cannot be placed on the ground then the tire force is always of zero magnitude. A tire touching the ground at maximum suspension droop, on the other hand, has zero measured load because the spring generates zero force at maximum droop. By editing PxVehicleTireLoadFilterData it is possible to generate tire forces even when there is very little load actually acting on the tire.</p> +</div> +</div></blockquote> +</div></blockquote> +</div> +<div class="section" id="pxvehicledifferential4wdata"> +<h3>PxVehicleDifferential4WData<a class="headerlink" href="#pxvehicledifferential4wdata" title="Permalink to this headline">¶</a></h3> +<p>mType:</p> +<blockquote> +<div>A number of differential types are supported: 4-wheel drive with open differential, 4-wheel drive with limited slip, front-wheel drive with open differential, front-wheel drive with limited slip, rear-wheel drive with open differential, rear-wheel drive with limited slip.</div></blockquote> +<p>mFrontRearSplit:</p> +<blockquote> +<div>If a 4-wheel drive differential is chosen (open or limited slip) this option allows the drive torque to be split unevenly between the front and rear wheels. Choosing a value of 0.5 delivers an equal split of the torque between the front and rear wheels; that is, the total torque delivered to the front wheels is equal to the total torque delivered to the rear wheels. Choosing a value greater than 0.5 delivers more torque to the front wheels, while choosing a value less than 0.5 delivers more torque to the rear wheels. This value is ignored for front-wheel drive and rear-wheel drive differentials.</div></blockquote> +<p>mFrontLeftRightSplit:</p> +<blockquote> +<div>This is similar to the Front Rear Split but instead splits the torque that is available for the front wheels between the front-left and front-right wheels. A value greater than 0.5 delivers more torque to the front-left wheel, while a value less than 0.5 delivers more torque to the front-right wheel. This parameter can be used to prevent any torque being delivered to a damaged or disabled wheel. This value is ignored for rear-wheel drive.</div></blockquote> +<p>mRearLeftRightSplit:</p> +<blockquote> +<div>This is similar to mFrontLeftRightSplit except that it applies to the rear wheels instead of the front wheels. This value is ignored for front-wheel drive.</div></blockquote> +<p>mFrontBias:</p> +<blockquote> +<div><p>Limited slip differentials work by only allowing a certain difference in wheel rotation speed to accumulate. This prevents the situation where one wheel is slipping but ends up taking all the available power. Further, by allowing a small difference in wheel rotation speed to accumulate it is possible for the vehicle to easily corner by permitting the outside wheel to rotate quicker than the inside wheel.</p> +<p>This parameter describes the maximum difference in wheel rotation speed that is allowed to accumulate. The front bias is the maximum of the two front-wheel rotation speeds divided by the minimum of the two front-wheel rotation speeds. When this ratio exceeds the value of the front bias the differential diverts torque from the faster wheel to the slower wheel in an attempt to preserve the maximum allowed wheel rotation speed ratio.</p> +<p>This value is ignored except for front-wheel drive or four wheel drive with limited slip.</p> +<p>A good starting value is around 1.3.</p> +</div></blockquote> +<p>mRearBias:</p> +<blockquote> +<div><p>This is similar to mFrontBias except that it refers to the rear wheels.</p> +<p>This value is ignored except for rear-wheel drive or four wheel drive with limited slip.</p> +<p>A good starting value is around 1.3.</p> +</div></blockquote> +<p>mCentreBias:</p> +<blockquote> +<div><p>This value is similar to the mFrontBias and mRearBias, except that it refers to the sum of the front wheel rotation speeds and the sum of the rear wheel rotation speeds.</p> +<p>This value is ignored except for four wheel drive with limited slip.</p> +<p>A good starting value is around 1.3.</p> +</div></blockquote> +</div> +<div class="section" id="pxrigiddynamic"> +<h3>PxRigidDynamic<a class="headerlink" href="#pxrigiddynamic" title="Permalink to this headline">¶</a></h3> +<p>Moment of Inertia:</p> +<blockquote> +<div><p>The moment of inertia of the rigid body is an extremely important parameter when editing vehicles because it affects the turning and rolling of the vehicle.</p> +<p>A good starting point for the moment of inertia of the rigid body is to work out the moment of inertia of the cuboid that bounds the chassis geometry. If the bounding cuboid is W wide, H high, and L long then the moment of inertia for a vehicle of mass M is:</p> +<blockquote> +<div>((L*L+H*H)*M/12, (W*W+L*L)*M/12, (H*H+W*W)*M/12)</div></blockquote> +<p>However, this is only a rough guide. Tweaking each value will modify the motion around the corresponding axis, with higher values making it harder to induce rotational speed from tire and suspension forces.</p> +<p>Providing unphysical values for the moment of inertia will result in either very sluggish behavior or extremely twitchy and perhaps even unstable behavior. The moment of inertia must at least approximately reflect the length scales of the suspension and tire force application points.</p> +<p>This parameter should be viewed as one of the first go-to editable values.</p> +</div></blockquote> +<p>Center of mass:</p> +<blockquote> +<div><p>Along with the moment of inertia, the center of mass is one of the first go-to editable values and, as such, has a profound effect on handling.</p> +<p>To discuss the center of mass it is useful to consider a typical 4-wheeled vehicle with a chassis mesh whose origin is at the center of the four wheels. There is no requirement on the origin being at the center of the four wheels but it does make the following discussion a little simpler. It might be expected that the center of mass lies somewhere near this origin because vehicles are designed in a way that spreads the load almost evenly between the four wheels. More specifically, it might be expected that the center of mass needs to be a little above the base of the chassis rather than at the height of the wheels. After all, vehicles have higher mass density near the bottom of the chassis due to density of the engine and other mechanical systems. As a consequence, it is expected that the center of mass is nearer the bottom of the chassis than the top, but definitely above the bottom. Without a particularly detailed analysis of the chassis density distribution the exact location along the vertical axis is really a little arbitrary and subjective. Along the forward direction it might be expected that the center of mass is a little nearer the front wheels than the rear wheels because of the mass of the front-located engine. Thinking about these factors allows the center of mass to be tweaked along the vertical and forward directions.</p> +<p>Tweaking the center of mass is really all about making incremental changes that tune the handling towards a desired goal. Moving the center of mass forwards should help cornering because more load is distributed to the front tires. However, this comes at the expense of reduced load on the rear tires, meaning that the car might turn more quickly only to spin out because the rear tires lose grip more quickly. Small changes followed by tests on the handling are required.</p> +<p>When setting the center of mass it is important to bear in mind that the suspension sprung mass values might require simultaneous updating. If the center of mass moves nearer the front this means that more mass is supported by the front suspensions and less by the rear suspensions. This change needs to be reflected in a consistent way. It is possible to mathematically describe the relationship between center of mass and the mass split between the suspensions. However, the editing possibilities afforded by breaking this rigid link should allow more tweaking options.</p> +</div></blockquote> +<p>Mass:</p> +<blockquote> +<div>A typical car might have a mass of around 1500kg.</div></blockquote> +</div> +</div> +<div class="section" id="troubleshooting"> +<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2> +<p>This Section introduces common solutions to common problems with vehicle tuning.</p> +<div class="section" id="jittery-vehicles"> +<h3>Jittery Vehicles<a class="headerlink" href="#jittery-vehicles" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Have PxInitVehicleSDK and PxVehicleSetBasisVectors been called before the first execution of PxVehicleUpdates? Check the error stream for warnings.</li> +<li>Does the length scale of PxTolerancesScale match the length scale of the vehicle (eg. 100 if centimeters are used)? Update PxTolerancesScale::length as appropriate.</li> +<li>Is the natural frequency of the spring too high/timestep of simulation too small for reliable simulation? See Section <a class="reference internal" href="#vehicle-suspension"><em>PxVehicleSuspensionData</em></a> for more details and update the natural frequency or timestep accordingly. Remember that the timestep can be updated per vehicle with PxVehicleWheelsSimData::setSubStepCount.</li> +<li>Are the maximum suspension droop and compression set to values that allow some suspension motion?</li> +</ol> +</div> +<div class="section" id="the-engine-rotation-refuses-to-spin-quickly"> +<h3>The Engine Rotation Refuses To Spin Quickly<a class="headerlink" href="#the-engine-rotation-refuses-to-spin-quickly" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Are the tires resisting the engine motion through excessive friction forces? Place the car very high above the ground and accelerate the engine to see if the engine and wheels start to spin round.</li> +<li>Do the engine's moment of inertia, peak torque and damping rates reflect the length scale? Note the documented SI units of each variable and recompute the values as appropriate.</li> +<li>Is the moment of inertia too large? A value of 1 or its equivalent in the relevant length scale is a good estimate for testing purposes.</li> +<li>Is the peak torque too small to drive the engine? Scale the default peak torque value with the mass of the vehicle with the knowledge that the default value will drive a standard car of around 1500kg.</li> +<li>Does the torque curve contain sensible values? Try a flat curve with each data point having a y-value of 1.0.</li> +<li>Is the maximum engine angular speed a realistic value? Consult any available manufacturer data for typical values or revert to the default value for testing purposes.</li> +<li>Are any of the damping rates too high? Reduce the damping rates and test.</li> +</ol> +</div> +<div class="section" id="the-engine-spins-but-the-wheels-refuse-to-spin"> +<h3>The Engine Spins But the Wheels Refuse To Spin<a class="headerlink" href="#the-engine-spins-but-the-wheels-refuse-to-spin" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Is the vehicle in neutral gear? Connect the engine to the wheels by setting the vehicle to first gear and disabling the autobox.</li> +<li>Does the differential deliver drive torque to the wheels (for PxVehicleNW vehicles only)? Make sure that the differential is properly configured.</li> +<li>Is the brake or handbrake engaged? Ensure that the brake and handbrake are both zero.</li> +<li>Do the wheels' moment of inertia and damping rates reflect the length scale? Note the documented SI units of each variable and recompute the values as appropriate.</li> +<li>Are the wheels' moments of inertia too high? Recompute the wheels' moments of inertia.</li> +<li>Are the wheels' damping rates too high? Reduce the wheels' damping rates.</li> +<li>Are the tires resisting the engine motion through excessive friction forces? Place the car very high above the ground and accelerate the engine to see if the engine and wheels start to spin round.</li> +</ol> +</div> +<div class="section" id="the-wheels-are-spinning-but-the-vehicle-does-not-move-forwards"> +<h3>The Wheels Are Spinning But The Vehicle Does Not Move Forwards<a class="headerlink" href="#the-wheels-are-spinning-but-the-vehicle-does-not-move-forwards" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Is the filtering configured so that the vehicle is supported only by suspension forces? Check the filtering configuration for shapes attached to the vehicle's rigid body actor, search for contacts involving shapes attached to the vehicle's actor using PVD.</li> +<li>Is sufficient friction being delivered to the tire contact patch? Query the friction values experienced by the tires during the execution of PxVehicleUpdates using PxVehicleWheelsDynData::getTireFriction.</li> +<li>Do the suspension forces (and the loads on the tires) reflect the mass of the rigid body actor? Query the suspension forces using PxVehicleWheelsDynData::getSuspensionForce. A 4-wheeled vehicle should generate suspension forces of approximately actorMass*gravity/4. Adjust the sprung masses of the vehicle suspensions to ensure that the driven wheels experience significant tire load.</li> +<li>Do the tires generate significant longitudinal tire forces? Use PxVehicleWheelsDynData::getTireLongSlip to check that the longitudinal slip of the tire is non-zero and approaches 1.0 when the wheels are spinning quickly without forward motion. Ensure that PxVehicleSetBasisVectors has been called with the correct forward vector if the longitudinal slip is vanishingly small. Further test that the forward vector has been set correctly by using PxVehicleWheelsDynData::getTireLongitudinalDir.</li> +<li>Is the tire longitudinal stiffness too small? Adjust the longitudinal stiffness back to the default value and test.</li> +<li>Is the mass of the vehicle's rigid body actor too large to be driven by the engine peak torque? Test that the mass of the actor is a sensible value and set accordingly.</li> +<li>Is the rigid body actor in a PhysX scene and is the scene being updated? Ensure that the actor is not asleep and participates in the scene update.</li> +</ol> +</div> +<div class="section" id="the-vehicle-does-not-steer-turn"> +<h3>The Vehicle Does Not Steer/Turn<a class="headerlink" href="#the-vehicle-does-not-steer-turn" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Is the moment of inertia of the vehicle too large so that it resists turning motion? Check that the moment of inertia of the vehicle's rigid body actor is a sensible value. Use the moment of inertia of a box with width/height/length of the vehicle as a starting guess for the moment of inertia of the actor.</li> +<li>Are the steer wheels receiving a steer angle? Check the steer angle with PxVehicleWheelsDynData::getSteer. If the steer angle is zero or smaller than expected check that a steer angle is being passed to the vehicle and that the maximum steer angles of the steer wheels are sensible values.</li> +<li>Do the steer wheels have a sensible lateral slip angle? Use PxVehicleWheelsDynData::getLatSlip to query the slip angles. Ensure that PxVehicleSetBasisVectors has been called with the correct forward and up vectors if the lateral slips are vanishingly small. Further test that the basis vector have been set correctly by using PxVehicleWheelsDynData::getTireLateralDir.</li> +<li>Is the lateral stiffness of the tire configured properly? Reset the tires back to their default values and retest.</li> +</ol> +</div> +<div class="section" id="the-acceleration-feels-sluggish"> +<h3>The Acceleration Feels Sluggish<a class="headerlink" href="#the-acceleration-feels-sluggish" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Are the damping rates of the engine and wheels too large? Reduce the engine damping rate, then the wheel damping rates and retest each time.</li> +<li>Is the vehicle stuck in the same gear all the time? Disable the autobox and change gears manually to test if the autobox is failing to switch gear. Check the autobox settings to make sure that it will automatically increase the gear at sensible engine rotation speeds.</li> +<li>Is the engine powerful enough to quickly accelerate the car? Increase the peak torque of the engine.</li> +<li>Do the wheels have high moments of inertia that prevent significant longitudinal slips developing? Reduce the moments of inertia of the wheels.</li> +</ol> +</div> +<div class="section" id="the-vehicle-does-not-slow-down-when-not-accelerating"> +<h3>The Vehicle Does Not Slow Down When Not Accelerating<a class="headerlink" href="#the-vehicle-does-not-slow-down-when-not-accelerating" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Are the wheel and engine damping rates too small? First increase the engine damping rate, then the wheel damping rates and retest each time.</li> +<li>Does the vehicle's rigid body actor have a velocity damping value? Increase as appropriate.</li> +</ol> +</div> +<div class="section" id="the-vehicle-turns-too-quickly-too-slowly"> +<h3>The Vehicle Turns Too Quickly/Too Slowly<a class="headerlink" href="#the-vehicle-turns-too-quickly-too-slowly" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Does the moment of inertia of the rigid body actor need tweaking? Adjust the component of the moment of inertia that corresponds to motion about the up vector. Increasing the moment of inertia will slow the turn rate, decreasing the moment of inertia will increase the turn rate.</li> +</ol> +</div> +<div class="section" id="the-wheels-spin-too-much-under-acceleration"> +<h3>The Wheels Spin Too Much Under Acceleration<a class="headerlink" href="#the-wheels-spin-too-much-under-acceleration" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Is the accelerator pedal value increasing too rapidly from 0 to 1? Slow down the rate of increase of the accelerator pedal value by filtering the controller or keyboard. Remember that aggressively pressing the accelerator pedal on a powerful car ought to lead to wheel spin.</li> +<li>Are the wheel moments of inertia too low? Increase the wheel moments of inertia.</li> +</ol> +</div> +<div class="section" id="the-wheels-spin-too-much-when-cornering"> +<h3>The Wheels Spin Too Much When Cornering<a class="headerlink" href="#the-wheels-spin-too-much-when-cornering" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Does the vehicle have a limited slip differential? If applicable set the differential type to limited slip and adjust the differential biases accordingly.</li> +</ol> +</div> +<div class="section" id="the-vehicle-never-goes-beyond-first-gear"> +<h3>The Vehicle Never Goes Beyond First Gear<a class="headerlink" href="#the-vehicle-never-goes-beyond-first-gear" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Does the vehicle cycle between first gear and neutral? If the autobox is enabled then the problem is probably that the latency of the autobox is shorter than the time spent performing a gear change. The autobox latency controls the minimum time spent in-between automated gear changes. After an automated gear change is initiated the autobox will not make another gear change decision until the latency time has passed. During a gear change the vehicle enters neutral gear and the accelerator pedal is uncoupled from the engine, meaning that the engine will slow down during the gear change. When the vehicle enters the target gear at the end of the gear change the autobox might decide immediately that the engine is too slow for the target gear and immediately initiate a downwards gear change. This will immediately put the car back in neutral, meaning that the car spends a very long time in neutral and never reaches its target gear. This will not happen if the autobox latency (PxVehicleAutoBoxData::setLatency) is set significantly larger than the gear switch time (PxVehicleGearsData::mSwitchTime).</li> +</ol> +</div> +<div class="section" id="the-vehicle-under-steers-then-over-steers"> +<h3>The Vehicle Under-steers Then Over-steers<a class="headerlink" href="#the-vehicle-under-steers-then-over-steers" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Is the vehicle on a bumpy surface? Edit the values in PxVehicleTireLoadFilterData so that the filtered normalized tire load has a flatter response to suspension compression.</li> +</ol> +</div> +<div class="section" id="the-vehicle-slows-down-unnaturally"> +<h3>The Vehicle Slows Down Unnaturally<a class="headerlink" href="#the-vehicle-slows-down-unnaturally" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Does the vehicle not slow down smoothly to rest? Take a look at the longitudinal slip values to see if they are oscillating between positive and negative. If there is a strong oscillation then two options are available that can be used separately or in conjunction with each other. The first option is to use PxVehicleWheelsSimData::setSubStepCount to force more vehicle update sub-steps as the forward speed of the vehicle approaches zero. The second option is to use PxVehicleWheelsSimData::setMinLongSlipDenominator to ensure that the denominator of the longitudinal slip never falls below a specified value.</li> +</ol> +</div> +<div class="section" id="the-vehicle-climbs-too-steep-slopes"> +<h3>The Vehicle Climbs Too Steep Slopes<a class="headerlink" href="#the-vehicle-climbs-too-steep-slopes" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li>Are the front wheels slipping badly? Modify PxVehicleTireData::mFrictionVsSlipGraph to reduce the available friction for slipping wheels.</li> +</ol> +</div> +</div> +<div class="section" id="references"> +<h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> +<div class="section" id="anti-roll-bar"> +<h3>Anti-roll Bar<a class="headerlink" href="#anti-roll-bar" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><a class="reference external" href="http://www.youtube.com/watch?v=_liGnV3PTiQ">http://www.youtube.com/watch?v=_liGnV3PTiQ</a> +<a class="reference external" href="http://en.wikipedia.org/wiki/Anti-roll_bar">http://en.wikipedia.org/wiki/Anti-roll_bar</a></div></blockquote> +</div> +<div class="section" id="tire-modeling"> +<h3>Tire Modeling<a class="headerlink" href="#tire-modeling" title="Permalink to this headline">¶</a></h3> +<p>The default tire model employed by PhysX vehicles is discussed in Appendix H of the CarSimEd documentation:</p> +<blockquote> +<div><a class="reference external" href="http://www.eggert.highpeakpress.com/ME485/Docs/CarSimEd.pdf">http://www.eggert.highpeakpress.com/ME485/Docs/CarSimEd.pdf</a></div></blockquote> +<p>PhysX vehicles allow any tire model to be simulated by specifying a tire shader, as discussed in <a class="reference internal" href="#tire-shaders"><em>Tire Shaders</em></a>. A tire model commonly used in engineering simulation is the Pacejka tire model:</p> +<blockquote> +<div><p><a class="reference external" href="http://phors.locost7.info/phors21.htm">http://phors.locost7.info/phors21.htm</a></p> +<p><a class="reference external" href="http://phors.locost7.info/phors22.htm">http://phors.locost7.info/phors22.htm</a></p> +</div></blockquote> +</div> +<div class="section" id="engine-torque-curves"> +<h3>Engine Torque Curves<a class="headerlink" href="#engine-torque-curves" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><a class="reference external" href="http://www.mitsubishi-fuso.com/en/technology/qanda/05_01.html?a5">http://www.mitsubishi-fuso.com/en/technology/qanda/05_01.html?a5</a></div></blockquote> +</div> +<div class="section" id="differentials"> +<h3>Differentials<a class="headerlink" href="#differentials" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><a class="reference external" href="http://www.howstuffworks.com/differential.htm">http://www.howstuffworks.com/differential.htm</a></div></blockquote> +</div> +<div class="section" id="clutch"> +<h3>Clutch<a class="headerlink" href="#clutch" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><a class="reference external" href="http://auto.howstuffworks.com/clutch.htm">http://auto.howstuffworks.com/clutch.htm</a></div></blockquote> +</div> +<div class="section" id="ackermann-steer-correction"> +<h3>Ackermann Steer Correction<a class="headerlink" href="#ackermann-steer-correction" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><a class="reference external" href="http://en.wikipedia.org/wiki/Ackermann_steering_geometry">http://en.wikipedia.org/wiki/Ackermann_steering_geometry</a></div></blockquote> +</div> +<div class="section" id="tanks"> +<h3>Tanks<a class="headerlink" href="#tanks" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><a class="reference external" href="http://www.wikihow.com/Drive-an-Abbot-SPG-%28Tank%29">http://www.wikihow.com/Drive-an-Abbot-SPG-%28Tank%29</a></div></blockquote> +</div> +<div class="section" id="general"> +<h3>General<a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p><a class="reference external" href="http://phors.locost7.info/intro.htm">http://phors.locost7.info/intro.htm</a></p> +<p><a class="reference external" href="http://www.millikenresearch.com/rcvd.html">http://www.millikenresearch.com/rcvd.html</a></p> +<p><a class="reference external" href="http://www.sciencedirect.com/science/book/9780750651127">http://www.sciencedirect.com/science/book/9780750651127</a></p> +</div></blockquote> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Vehicles</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#algorithm">Algorithm</a></li> +<li><a class="reference internal" href="#first-code">First Code</a><ul> +<li><a class="reference internal" href="#vehicle-sdk-initialization">Vehicle SDK Initialization</a></li> +<li><a class="reference internal" href="#introduction-to-vehicle-creation">Introduction To Vehicle Creation</a></li> +<li><a class="reference internal" href="#introduction-to-vehicle-update">Introduction To Vehicle Update</a></li> +</ul> +</li> +<li><a class="reference internal" href="#snippets">Snippets</a><ul> +<li><a class="reference internal" href="#snippetvehicle4w">SnippetVehicle4W</a></li> +<li><a class="reference internal" href="#snippetvehicletank">SnippetVehicleTank</a></li> +<li><a class="reference internal" href="#snippetvehiclenodrive">SnippetVehicleNoDrive</a></li> +<li><a class="reference internal" href="#snippetvehiclescale">SnippetVehicleScale</a></li> +<li><a class="reference internal" href="#snippetvehiclemultithreading">SnippetVehicleMultiThreading</a></li> +</ul> +</li> +<li><a class="reference internal" href="#advanced-concepts">Advanced Concepts</a><ul> +<li><a class="reference internal" href="#vehicle-creation">Vehicle Creation</a><ul> +<li><a class="reference internal" href="#setupwheelssimulationdata">setupWheelsSimulationData</a></li> +<li><a class="reference internal" href="#setupdrivesimdata">setupDriveSimData</a></li> +<li><a class="reference internal" href="#setupvehicleactor">setupVehicleActor</a></li> +</ul> +</li> +<li><a class="reference internal" href="#filtering">Filtering</a></li> +<li><a class="reference internal" href="#tire-friction-on-drivable-surfaces">Tire Friction on Drivable Surfaces</a></li> +<li><a class="reference internal" href="#vehicle-controls">Vehicle Controls</a></li> +<li><a class="reference internal" href="#vehicle-update">Vehicle Update</a><ul> +<li><a class="reference internal" href="#raycast-and-update-ordering">Raycast and Update Ordering</a></li> +<li><a class="reference internal" href="#wheel-pose">Wheel Pose</a></li> +<li><a class="reference internal" href="#vehicle-state-queries">Vehicle State Queries</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#more-advanced-concepts">More Advanced Concepts</a><ul> +<li><a class="reference internal" href="#vehicle-telemetry">Vehicle Telemetry</a></li> +<li><a class="reference internal" href="#vehicle-update-multi-threaded">Vehicle Update Multi-Threaded</a></li> +<li><a class="reference internal" href="#tire-shaders">Tire Shaders</a></li> +<li><a class="reference internal" href="#vehicle-types">Vehicle Types</a><ul> +<li><a class="reference internal" href="#pxvehicledrive4w">PxVehicleDrive4W</a><ul> +<li><a class="reference internal" href="#wheeled-cars">3-Wheeled Cars</a></li> +<li><a class="reference internal" href="#n-wheeled-cars">N-Wheeled Cars</a></li> +</ul> +</li> +<li><a class="reference internal" href="#pxvehicledrivenw">PxVehicleDriveNW</a></li> +<li><a class="reference internal" href="#pxvehicledrivetank">PxVehicleDriveTank</a></li> +<li><a class="reference internal" href="#pxvehiclenodrive">PxVehicleNoDrive</a></li> +</ul> +</li> +<li><a class="reference internal" href="#si-units">SI Units</a></li> +<li><a class="reference internal" href="#level-of-detail">Level of Detail</a><ul> +<li><a class="reference internal" href="#extrapolation">Extrapolation</a></li> +<li><a class="reference internal" href="#disable-wheels">Disable Wheels</a></li> +<li><a class="reference internal" href="#swapping-multiple-vehicle-versions">Swapping Multiple Vehicle Versions</a></li> +<li><a class="reference internal" href="#disable-raycasts">Disable Raycasts</a></li> +<li><a class="reference internal" href="#use-the-clutch-in-estimate-mode">Use The Clutch in Estimate Mode</a></li> +</ul> +</li> +<li><a class="reference internal" href="#wheel-contact-beyond-raycasts">Wheel Contact Beyond Raycasts</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tuning-guide">Tuning Guide</a><ul> +<li><a class="reference internal" href="#pxvehiclewheeldata">PxVehicleWheelData</a></li> +<li><a class="reference internal" href="#pxvehiclewheelssimdata">PxVehicleWheelsSimData</a></li> +<li><a class="reference internal" href="#pxvehiclesuspensiondata">PxVehicleSuspensionData</a></li> +<li><a class="reference internal" href="#pxvehicleantirollbar">PxVehicleAntiRollBar</a></li> +<li><a class="reference internal" href="#pxvehicletiredata">PxVehicleTireData</a></li> +<li><a class="reference internal" href="#pxvehicleenginedata">PxVehicleEngineData</a></li> +<li><a class="reference internal" href="#pxvehiclegearsdata">PxVehicleGearsData</a></li> +<li><a class="reference internal" href="#pxvehicleautoboxdata">PxVehicleAutoBoxData</a></li> +<li><a class="reference internal" href="#pxvehicleclutchdata">PxVehicleClutchData</a></li> +<li><a class="reference internal" href="#pxvehicleackermanngeometrydata">PxVehicleAckermannGeometryData</a></li> +<li><a class="reference internal" href="#pxvehicletireloadfilterdata">PxVehicleTireLoadFilterData</a></li> +<li><a class="reference internal" href="#pxvehicledifferential4wdata">PxVehicleDifferential4WData</a></li> +<li><a class="reference internal" href="#pxrigiddynamic">PxRigidDynamic</a></li> +</ul> +</li> +<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul> +<li><a class="reference internal" href="#jittery-vehicles">Jittery Vehicles</a></li> +<li><a class="reference internal" href="#the-engine-rotation-refuses-to-spin-quickly">The Engine Rotation Refuses To Spin Quickly</a></li> +<li><a class="reference internal" href="#the-engine-spins-but-the-wheels-refuse-to-spin">The Engine Spins But the Wheels Refuse To Spin</a></li> +<li><a class="reference internal" href="#the-wheels-are-spinning-but-the-vehicle-does-not-move-forwards">The Wheels Are Spinning But The Vehicle Does Not Move Forwards</a></li> +<li><a class="reference internal" href="#the-vehicle-does-not-steer-turn">The Vehicle Does Not Steer/Turn</a></li> +<li><a class="reference internal" href="#the-acceleration-feels-sluggish">The Acceleration Feels Sluggish</a></li> +<li><a class="reference internal" href="#the-vehicle-does-not-slow-down-when-not-accelerating">The Vehicle Does Not Slow Down When Not Accelerating</a></li> +<li><a class="reference internal" href="#the-vehicle-turns-too-quickly-too-slowly">The Vehicle Turns Too Quickly/Too Slowly</a></li> +<li><a class="reference internal" href="#the-wheels-spin-too-much-under-acceleration">The Wheels Spin Too Much Under Acceleration</a></li> +<li><a class="reference internal" href="#the-wheels-spin-too-much-when-cornering">The Wheels Spin Too Much When Cornering</a></li> +<li><a class="reference internal" href="#the-vehicle-never-goes-beyond-first-gear">The Vehicle Never Goes Beyond First Gear</a></li> +<li><a class="reference internal" href="#the-vehicle-under-steers-then-over-steers">The Vehicle Under-steers Then Over-steers</a></li> +<li><a class="reference internal" href="#the-vehicle-slows-down-unnaturally">The Vehicle Slows Down Unnaturally</a></li> +<li><a class="reference internal" href="#the-vehicle-climbs-too-steep-slopes">The Vehicle Climbs Too Steep Slopes</a></li> +</ul> +</li> +<li><a class="reference internal" href="#references">References</a><ul> +<li><a class="reference internal" href="#anti-roll-bar">Anti-roll Bar</a></li> +<li><a class="reference internal" href="#tire-modeling">Tire Modeling</a></li> +<li><a class="reference internal" href="#engine-torque-curves">Engine Torque Curves</a></li> +<li><a class="reference internal" href="#differentials">Differentials</a></li> +<li><a class="reference internal" href="#clutch">Clutch</a></li> +<li><a class="reference internal" href="#ackermann-steer-correction">Ackermann Steer Correction</a></li> +<li><a class="reference internal" href="#tanks">Tanks</a></li> +<li><a class="reference internal" href="#general">General</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="SceneQueries.html" + title="previous chapter">Scene Queries</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="CharacterControllers.html" + title="next chapter">Character Controllers</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" /> + <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="CharacterControllers.html" title="Character Controllers" + >next</a></li> + <li class="right" > + <a href="SceneQueries.html" title="Scene Queries" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file diff --git a/PhysX_3.4/Documentation/PhysXGuide/Manual/VisualDebugger.html b/PhysX_3.4/Documentation/PhysXGuide/Manual/VisualDebugger.html new file mode 100644 index 00000000..f7a5278c --- /dev/null +++ b/PhysX_3.4/Documentation/PhysXGuide/Manual/VisualDebugger.html @@ -0,0 +1,275 @@ +<!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>PhysX Visual Debugger (PVD) — NVIDIA PhysX SDK 3.4.0 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/breathe.css" type="text/css" /> + + <script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: '../', + VERSION: '3.4.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 PhysX SDK 3.4.0 Documentation" href="../index.html" /> + <link rel="up" title="User's Guide" href="Index.html" /> + <link rel="next" title="Simulation Statistics" href="Statistics.html" /> + <link rel="prev" title="Debug Visualization" href="DebugVisualization.html" /> + </head> + <body> + <div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="Statistics.html" title="Simulation Statistics" + accesskey="N">next</a></li> + <li class="right" > + <a href="DebugVisualization.html" title="Debug Visualization" + accesskey="P">previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" accesskey="U">User's Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="physx-visual-debugger-pvd"> +<span id="physxvisualdebugger"></span><h1>PhysX Visual Debugger (PVD)<a class="headerlink" href="#physx-visual-debugger-pvd" title="Permalink to this headline">¶</a></h1> +<div class="section" id="pvd"> +<h2>PVD<a class="headerlink" href="#pvd" title="Permalink to this headline">¶</a></h2> +<div class="figure align-center"> +<img alt="../_images/PvdScreenshot.png" src="../_images/PvdScreenshot.png" /> +</div> +<p>The PhysX Visual Debugger (PVD) provides a graphical view of the PhysX scene and includes various tools to inspect and visualize variables of every PhysX object. Additionally it can also record and visualize memory and timing data.</p> +<p>PVD can be downloaded from: <a class="reference external" href="http://supportcenteronline.com/ics/support/default.asp?deptID=1949">http://supportcenteronline.com/ics/support/default.asp?deptID=1949</a></p> +<p>Questions regarding the usage of the GUI should all be answered by its detailed built-in help.</p> +</div> +<div class="section" id="basic-setup-sdk-side"> +<h2>Basic Setup (SDK Side)<a class="headerlink" href="#basic-setup-sdk-side" title="Permalink to this headline">¶</a></h2> +<p>PVD integration is enabled in the debug, checked and profiling configurations of the SDK. In order to reduce memory footprint and code size, it is not enabled in the release configuration.</p> +<p>The SDK outputs the PVD debugging data in form of a stream. PVD supports reading the stream either from a TCP/IP network socket or from a file.</p> +<div class="section" id="network-setup"> +<h3>Network Setup<a class="headerlink" href="#network-setup" title="Permalink to this headline">¶</a></h3> +<p>Streaming to TCP/IP is supported on almost all platforms, and is usually the most convenient way to collect PVD data. In this mode the stream can be watched in real-time, depending on network speed and scene complexity. In network mode PVD acts as a TCP/IP server and must therefore be launched before the SDK tries to connect to it. The default listening port is 5425:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">use</span> <span class="k">namespace</span> <span class="n">physx</span><span class="p">;</span> + +<span class="n">PxPvd</span><span class="o">*</span> <span class="n">pvd</span> <span class="o">=</span> <span class="n">PxCreatePvd</span><span class="p">(</span><span class="o">*</span><span class="n">foundation</span><span class="p">);</span> +<span class="n">PxPvdTransport</span><span class="o">*</span> <span class="n">transport</span> <span class="o">=</span> <span class="n">PxDefaultPvdSocketTransportCreate</span><span class="p">(</span><span class="n">PVD_HOST</span><span class="p">,</span> <span class="mi">5425</span><span class="p">,</span> <span class="mi">10</span><span class="p">);</span> +<span class="n">pvd</span><span class="o">-></span><span class="n">connect</span><span class="p">(</span><span class="o">*</span><span class="n">transport</span><span class="p">,</span><span class="n">PxPvdInstrumentationFlag</span><span class="o">::</span><span class="n">eALL</span><span class="p">);</span> + +<span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span> <span class="o">=</span> <span class="n">PxCreatePhysics</span><span class="p">(</span><span class="n">PX_PHYSICS_VERSION</span><span class="p">,</span> <span class="o">*</span><span class="n">gFoundation</span><span class="p">,</span> <span class="n">PxTolerancesScale</span><span class="p">(),</span> <span class="nb">true</span><span class="p">,</span> <span class="n">pvd</span><span class="p">);</span> + +<span class="c1">//After releasing PxPhysics, release the PVD</span> +<span class="n">physics</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">pvd</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">transport</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +</div> +<div class="section" id="file-setup"> +<h3>File Setup<a class="headerlink" href="#file-setup" title="Permalink to this headline">¶</a></h3> +<p>Streaming to file is an alternative to network streams. This is the recommended fall-back in case your platform or system setup does not support a network connection to PVD. File streams are often faster than network sockets and therefore a good alternative if performance is more important than real-time viewing. +Streams stored as files can be loaded by drag&drop or over the File->Load menu in PVD:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">use</span> <span class="k">namespace</span> <span class="n">physx</span><span class="p">;</span> + +<span class="n">PxPvd</span><span class="o">*</span> <span class="n">pvd</span> <span class="o">=</span> <span class="n">PxCreatePvd</span><span class="p">(</span><span class="o">*</span><span class="n">foundation</span><span class="p">);</span> +<span class="n">PxPvdTransport</span><span class="o">*</span> <span class="n">transport</span> <span class="o">=</span> <span class="n">PxDefaultPvdFileTransportCreate</span><span class="p">(</span><span class="n">filename</span><span class="p">);</span> +<span class="n">pvd</span><span class="o">-></span><span class="n">connect</span><span class="p">(</span><span class="o">*</span><span class="n">transport</span><span class="p">,</span><span class="n">PxPvdInstrumentationFlag</span><span class="o">::</span><span class="n">eALL</span><span class="p">);</span> + +<span class="n">PxPhysics</span><span class="o">*</span> <span class="n">physics</span> <span class="o">=</span> <span class="n">PxCreatePhysics</span><span class="p">(</span><span class="n">PX_PHYSICS_VERSION</span><span class="p">,</span> <span class="o">*</span><span class="n">gFoundation</span><span class="p">,</span> <span class="n">PxTolerancesScale</span><span class="p">(),</span><span class="nb">true</span><span class="p">,</span> <span class="n">pvd</span><span class="p">);</span> + +<span class="c1">//After releasing PxPhysics, release the PVD</span> +<span class="n">physics</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">pvd</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +<span class="n">transport</span><span class="o">-></span><span class="n">release</span><span class="p">();</span> +</pre></div> +</div> +</div> +</div> +<div class="section" id="advanced-setup"> +<h2>Advanced Setup<a class="headerlink" href="#advanced-setup" title="Permalink to this headline">¶</a></h2> +<div class="section" id="connection-flags"> +<h3>Connection Flags<a class="headerlink" href="#connection-flags" title="Permalink to this headline">¶</a></h3> +<p>To optimize the stream size we provide flags to enable specific features. This has both influence on PVD's and the SDK's performance:</p> +<ul class="simple"> +<li><strong>PxPvdInstrumentationFlag::eDEBUG</strong>: Transfer all debug data to visualize and inspect objects. This flag has usually the biggest impact on the stream's size.</li> +<li><strong>PxPvdInstrumentationFlag::ePROFILE</strong>: Transfer timing information of various profiling zones in our SDK.</li> +<li><strong>PxPvdInstrumentationFlag::eMEMORY</strong>: Transfer memory usage data of our SDK.</li> +</ul> +<p>Setup to transfer only profiling data over network:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">pvd</span><span class="o">-></span><span class="n">connect</span><span class="p">(</span><span class="o">*</span><span class="n">transport</span><span class="p">,</span> <span class="n">PxPvdInstrumentationFlag</span><span class="o">::</span><span class="n">ePROFILE</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="visualizing-externals-and-extended-data"> +<h3>Visualizing Externals and Extended Data<a class="headerlink" href="#visualizing-externals-and-extended-data" title="Permalink to this headline">¶</a></h3> +<p>Joints are implemented as an extension to the SDK constraints and therefore need special handling to get transmitted to PVD. +Both joint and contact data can increase the stream size significantly. Visualizing it in PVD is therefore disabled by default. To enable them use following API calls:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mScene</span><span class="o">-></span><span class="n">getScenePvdClient</span><span class="p">()</span><span class="o">-></span><span class="n">setScenePvdFlags</span><span class="p">(</span><span class="n">PxPvdSceneFlag</span><span class="o">::</span><span class="n">eTRANSMIT_CONSTRAINTS</span> <span class="o">|</span> <span class="n">PxPvdSceneFlag</span><span class="o">::</span><span class="n">eTRANSMIT_SCENEQUERIES</span> <span class="o">|</span> <span class="n">PxPvdSceneFlag</span><span class="o">::</span><span class="n">eTRANSMIT_CONTACTS</span><span class="p">);</span> +</pre></div> +</div> +<p>or set the flags separately:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mScene</span><span class="o">-></span><span class="n">getScenePvdClient</span><span class="p">()</span><span class="o">-></span><span class="n">setScenePvdFlag</span><span class="p">(</span><span class="n">PxPvdSceneFlag</span><span class="o">::</span><span class="n">eTRANSMIT_CONSTRAINTS</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="visualizing-scenequery"> +<h3>Visualizing SceneQuery<a class="headerlink" href="#visualizing-scenequery" title="Permalink to this headline">¶</a></h3> +<p>Visualizing SceneQuery in PVD is disabled by default since queries and hits data can increase the stream size significantly. To enable it use following API calls:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="n">mScene</span><span class="o">-></span><span class="n">getScenePvdClient</span><span class="p">()</span><span class="o">-></span><span class="n">setScenePvdFlag</span><span class="p">(</span><span class="n">PxPvdSceneFlag</span><span class="o">::</span><span class="n">eTRANSMIT_SCENEQUERIES</span><span class="p">,</span> <span class="nb">true</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="custom-pvdclient"> +<h3>Custom PvdClient<a class="headerlink" href="#custom-pvdclient" title="Permalink to this headline">¶</a></h3> +<p>Implement the PvdClient interface if your application needs to react upon connection or disconnection from PVD, or if you plan to send custom PVD events from your application. +It is recommended to toggle the contact and constraint visualization in the onPvdConnected/onPvdDisconnected callbacks to avoid potential memory and compute overhead in the SDK:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// derive from PvdClient</span> +<span class="k">struct</span> <span class="n">MyPvdClient</span> <span class="o">:</span> <span class="k">public</span> <span class="n">physx</span><span class="o">::</span><span class="n">pvdsdk</span><span class="o">::</span><span class="n">PvdClient</span> +<span class="p">{</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">onPvdConnected</span><span class="p">()</span> + <span class="p">{</span> + <span class="c1">// 1. create a PvdDataStream</span> + <span class="c1">// 2. send your custom PVD class descriptions from here</span> + <span class="c1">// this then allows PVD to correctly identify and represent</span> + <span class="c1">// custom data that is sent from your application to a PxVisualDebuggerConnection.</span> + <span class="c1">// example in JointConnectionHandler</span> + <span class="c1">// 3. do something when successfully connected</span> + <span class="c1">// e.g. enable contact and constraint visualization</span> + <span class="p">}</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="n">onPvdDisconnected</span><span class="p">()</span> + <span class="p">{</span> + <span class="c1">// handle disconnection, release PvdDataStream</span> + <span class="c1">// e.g. disable contact and constraint visualization</span> + <span class="p">}</span> + <span class="c1">//impleament other methods</span> + <span class="p">...</span> +<span class="p">};</span> + +<span class="c1">// register custom handler</span> +<span class="n">MyPvdClient</span> <span class="n">myPvdClient</span><span class="p">;</span> +<span class="n">pvd</span><span class="o">-></span><span class="n">addClient</span><span class="p">(</span><span class="n">myPvdClient</span><span class="p">);</span> +</pre></div> +</div> +</div> +<div class="section" id="pvd-error-stream"> +<h3>PVD Error Stream<a class="headerlink" href="#pvd-error-stream" title="Permalink to this headline">¶</a></h3> +<p>PhysX SDK sends all its own error messages to PVD if PVD is connected. +In addition, you can call Ps::Foundation::error() or Ps::Foundation::getErrorHandler()::reportError() to report your error message. These functions will send error messages to PVD automatically.</p> +<p>The messages will be listed in ErrorStream view of PVD.</p> +</div> +<div class="section" id="custom-profiling"> +<h3>Custom profiling<a class="headerlink" href="#custom-profiling" title="Permalink to this headline">¶</a></h3> +<p>When using PxPvdInstrumentationFlag::ePROFILE, PVD internally calls PxSetProfilerCallback() to set itself up as the current profiler. This happens during the PxPvd::connect() call, and it overrides the potentially already existing profiler callback. That is, if users call PxSetProfilerCallback() with their own user profiler callback, and then initialize PVD with PxPvdInstrumentationFlag::ePROFILE, then the user profiler callback is lost. Similarly, initializing PVD first then calling PxSetProfilerCallback() will make PVD's profiling results vanish.</p> +<p>In case both PVD's internal profiling and a user's custom profiling are needed at the same time, it is recommended to initialize PVD first, then call PxSetProfilerCallback() with your own profiler. In your implementation, call the PVD profiling functions manually, before or after performing your own profiling operations:</p> +<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">UserProfilerCallback</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PxProfilerCallback</span> +<span class="p">{</span> + <span class="n">PxPvd</span><span class="o">*</span> <span class="n">mPvd</span><span class="p">;</span> + + <span class="k">virtual</span> <span class="kt">void</span><span class="o">*</span> <span class="nf">zoneStart</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">eventName</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">detached</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">contextId</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// Do custom profiling here</span> + + <span class="c1">// Then re-route to PVD implementation</span> + <span class="k">return</span> <span class="n">mPvd</span><span class="o">-></span><span class="n">zoneStart</span><span class="p">(</span><span class="n">eventName</span><span class="p">,</span> <span class="n">detached</span><span class="p">,</span> <span class="n">contextId</span><span class="p">);</span> + <span class="p">}</span> + <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">zoneEnd</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span> <span class="n">profilerData</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">eventName</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">detached</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">contextId</span><span class="p">)</span> + <span class="p">{</span> + <span class="c1">// Do custom profiling here</span> + + <span class="c1">// Then re-route to PVD implementation</span> + <span class="n">mPvd</span><span class="o">-></span><span class="n">zoneEnd</span><span class="p">(</span><span class="n">profilerData</span><span class="p">,</span> <span class="n">eventName</span><span class="p">,</span> <span class="n">detached</span><span class="p">,</span> <span class="n">contextId</span><span class="p">);</span> + <span class="p">}</span> +<span class="p">};</span> +</pre></div> +</div> +<p>This is illustrated in SnippetCustomProfiler.</p> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../Index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">PhysX Visual Debugger (PVD)</a><ul> +<li><a class="reference internal" href="#pvd">PVD</a></li> +<li><a class="reference internal" href="#basic-setup-sdk-side">Basic Setup (SDK Side)</a><ul> +<li><a class="reference internal" href="#network-setup">Network Setup</a></li> +<li><a class="reference internal" href="#file-setup">File Setup</a></li> +</ul> +</li> +<li><a class="reference internal" href="#advanced-setup">Advanced Setup</a><ul> +<li><a class="reference internal" href="#connection-flags">Connection Flags</a></li> +<li><a class="reference internal" href="#visualizing-externals-and-extended-data">Visualizing Externals and Extended Data</a></li> +<li><a class="reference internal" href="#visualizing-scenequery">Visualizing SceneQuery</a></li> +<li><a class="reference internal" href="#custom-pvdclient">Custom PvdClient</a></li> +<li><a class="reference internal" href="#pvd-error-stream">PVD Error Stream</a></li> +<li><a class="reference internal" href="#custom-profiling">Custom profiling</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="DebugVisualization.html" + title="previous chapter">Debug Visualization</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="Statistics.html" + title="next chapter">Simulation Statistics</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" /> + <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="Statistics.html" title="Simulation Statistics" + >next</a></li> + <li class="right" > + <a href="DebugVisualization.html" title="Debug Visualization" + >previous</a> |</li> + <li><a href="../Index.html">NVIDIA PhysX SDK 3.4.0 Documentation</a> »</li> + <li><a href="Index.html" >User's Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2008-2014 NVIDIA Corporation, 2701 San Tomas Expressway, Santa Clara, CA 95050 U.S.A. All rights reserved. + </div> + </body> +</html>
\ No newline at end of file |