From 236f03c0b9a4982328ed1201978f7f69d192d9b2 Mon Sep 17 00:00:00 2001
From: Anton Novoselov <novoselov.ab@gmail.com>
Date: Tue, 1 Aug 2017 12:53:38 +0300
Subject: Blast 1.1 release (windows / linux)

see docs/release_notes.txt for details
---
 docs/api_docs/files/pageextphysx.html | 81 +++++++++++++++++------------------
 1 file changed, 40 insertions(+), 41 deletions(-)

(limited to 'docs/api_docs/files/pageextphysx.html')
diff --git a/docs/api_docs/files/pageextphysx.html b/docs/api_docs/files/pageextphysx.html
index 0d0c366..b1ee6ba 100644
--- a/docs/api_docs/files/pageextphysx.html
+++ b/docs/api_docs/files/pageextphysx.html
@@ -1,6 +1,6 @@
 <html>
 	<head>
-		<title>NVIDIA(R) Blast(R) SDK 1.0 API Reference: PhysX Extensions</title>
+		<title>NVIDIA(R) Blast(R) SDK 1.1 API Reference: PhysX Extensions (NvBlastExtPhysX)</title>
 		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 		<LINK HREF="NVIDIA.css" REL="stylesheet" TYPE="text/css">
 	</head>
@@ -20,8 +20,8 @@
 		</div>
 <!-- Generated by Doxygen 1.5.8 -->
 <div class="contents">
-<h1><a class="anchor" name="pageextphysx">PhysX Extensions </a></h1>NvBlastExtPhysX contains extensions for easier use of Blast Toolkit with the PhysX SDK. There are 3 of them:<ul>
-<li><b>ExtPxManager</b>: Manager to keep Blast Actors in sync with PhysX actors.</li><li><b>ExtImpactDamageManager</b>: Manager to collect and apply impact damage caused by collision in PhysX Scene.</li><li><b>ExtStressSolver</b>: Stress Solver to propagate stress through support graph and apply it as damage to Blast actors.</li></ul>
+<h1><a class="anchor" name="pageextphysx">PhysX Extensions (NvBlastExtPhysX) </a></h1>NvBlastExtPhysX contains classes for easier use of Blast Toolkit with the PhysX SDK. There are 3 of them:<ul>
+<li><b>ExtPxManager</b>: Manager to keep Blast Actors in sync with PhysX actors.</li><li><b>ExtImpactDamageManager</b>: Manager to collect and apply impact damage caused by collision in PhysX Scene.</li><li><b>ExtPxStressSolver</b>: Stress Solver to propagate stress through support graph and apply it as damage to Blast actors.</li></ul>
 <p>
 This library also contains an extension for synchronizing Blast state:<ul>
 <li><b>ExtSync</b> - Utility for writing Blast state to a buffer, to be read by a client. This may be used for networking, for example.</li></ul>
@@ -30,7 +30,7 @@ This library also contains an extension for synchronizing Blast state:<ul>
  <h2><a class="anchor" name="ExtPxManager">
 ExtPxManager</a></h2>
 <b>Physics Manager</b> - is a reference implementation for keeping Blast Actors synced with PhysX actors. It's main job is to listen for TkFamily events and update <em>PxScene</em> (by adding and removing PxActors) accordingly.<p>
-In order to use it create ExtPxManager:<p>
+In order to use it create an ExtPxManager. If we have a physx::PxPhysics object m_physics and a TkFramework m_tkFramework, use<p>
 <div class="fragment"><pre class="fragment">ExtPxManager* pxManager = ExtPxManager::create(m_physics, m_tkFramework);
 </pre></div><p>
 For every <em>TkAsset</em> prepare <em>ExtPxAsset</em>. Which contains <em>TkAsset</em> + collection of physics geometry for every chunk. Every chunk can contain any number of subchunks. Where each subchunk is basically PxConvexMeshGeometry with transform. Also every chunk can be marked as static (<em>isStatic</em> flag). If actor contains at least one static chunks in it's support graph it makes an actor kinematic (static), otherwise it's dynamic. Having zero subchunks makes chunk invisible in physics scene, it can be used for example to represent 'earth' as a special invisible static chunk and connect all near earth chunks to it.<p>
@@ -47,7 +47,7 @@ ExtPxFamily* family = pxManager-&gt;createFamily(desc);
 You can subscribe to family events in order to sync graphics (or anything else) with physics:<p>
 <div class="fragment"><pre class="fragment">family-&gt;subscribe(listener);
 </pre></div><p>
-Listener will be notified with all physics actors added and removed.<p>
+The listener will be notified with all physics actors added and removed.<p>
 And finally spawn the family in some world position (the first actor/actors will be created and event will be fired to the listener):<p>
 <div class="fragment"><pre class="fragment">ExtPxSpawnSettings spawnSettings = {
     &amp;pxScene,
@@ -55,24 +55,24 @@ And finally spawn the family in some world position (the first actor/actors will
     RIGIDBODY_DENSITY
 };
 
-family-&gt;spawn(PxTransform(0, 0, 0), spawnSettings);
+family-&gt;spawn(PxTransform(0, 0, 0), PxVec3(1, 1, 1), spawnSettings);
 </pre></div><p>
 You can get families actor's either from listening to events or by calling getActors(). Every <em>ExtPxActor</em> matches 1 &lt;-&gt; 1 with TkActor (which matches <em><a class="el" href="struct_nv_blast_actor.html">NvBlastActor</a></em> accordingly).<p>
 <div class="fragment"><pre class="fragment">ExtPxActor* actor = ....; 
 physx::PxRigidDynamic rigidDynamic = actor-&gt;getPxActor(); <span class="comment">// </span>
 </pre></div><p>
-ExtPxActor remains internally unchanged through it's life time. Use <em>ExtPxActor</em> <em>getChunkIndices()</em> and <em>getPxActor()</em> to update graphics representation. Sample code:<p>
-<div class="fragment"><pre class="fragment">    <span class="keyword">const</span> uint32_t* chunkIndices;
-    <span class="keywordtype">size_t</span> chunkIndexCount;
-    actor.getChunkIndices(chunkIndices, chunkIndexCount);
-    <span class="keywordflow">for</span> (uint32_t i = 0; i &lt; chunkIndexCount; i++)
+An ExtPxActor remains internally unchanged through its lifetime. Use <em>ExtPxActor</em> <em>getChunkIndices()</em> and <em>getPxActor()</em> to update your graphics representation. Sample code:<p>
+<div class="fragment"><pre class="fragment"><span class="keyword">const</span> uint32_t* chunkIndices;
+<span class="keywordtype">size_t</span> chunkIndexCount;
+actor.getChunkIndices(chunkIndices, chunkIndexCount);
+<span class="keywordflow">for</span> (uint32_t i = 0; i &lt; chunkIndexCount; i++)
+{
+    uint32_t chunkIndex = chunkIndices[i];
+    <span class="keywordflow">for</span> (Renderable* r : m_chunks[chunkIndex].renderables)
     {
-        uint32_t chunkIndex = chunkIndices[i];
-        <span class="keywordflow">for</span> (Renderable* r : m_chunks[chunkIndex].renderables)
-        {
-            r-&gt;setTransform(actor.getPxActor()-&gt;getGlobalPose() * pxAsset.chunks[chunkIndex].convexes[0].transform);
-        }
+        r-&gt;setTransform(actor.getPxActor()-&gt;getGlobalPose() * pxAsset.chunks[chunkIndex].convexes[0].transform);
     }
+}
 </pre></div><p>
 In order to use joints set joint create function with <em>ExtPxManager::setCreateJointFunction</em>(...). It will be called when new TkJoint's are being created. All the joint updates and remove will be handled by manager internally.<p>
 <br>
@@ -82,48 +82,47 @@ ExtImpactDamageManager</a></h2>
 In order to use it create it:<p>
 <div class="fragment"><pre class="fragment">ExtImpactDamageManager* impactManager = ExtImpactDamageManager::create(pxManager);
 </pre></div><p>
-Call it's onContact method on every <em>PxSimulationEventCallback</em> <em>onContact()</em> <p>
-<div class="fragment"><pre class="fragment">    <span class="keyword">class </span>EventCallback : <span class="keyword">public</span> PxSimulationEventCallback
-    {
-    <span class="keyword">public</span>:
-        EventCallback(ExtImpactDamageManager* manager) : m_manager(manager) {}
+Call its onContact method on every <em>PxSimulationEventCallback</em> <em>onContact()</em> <p>
+<div class="fragment"><pre class="fragment"><span class="keyword">class </span>EventCallback : <span class="keyword">public</span> PxSimulationEventCallback
+{
+<span class="keyword">public</span>:
+    EventCallback(ExtImpactDamageManager* manager) : m_manager(manager) {}
 
-        <span class="keyword">virtual</span> <span class="keywordtype">void</span> onContact(<span class="keyword">const</span> PxContactPairHeader&amp; pairHeader, <span class="keyword">const</span> PxContactPair* pairs, uint32_t nbPairs)
-        {
-            m_manager-&gt;onContact(pairHeader, pairs, nbPairs);
-        }
+    <span class="keyword">virtual</span> <span class="keywordtype">void</span> onContact(<span class="keyword">const</span> PxContactPairHeader&amp; pairHeader, <span class="keyword">const</span> PxContactPair* pairs, uint32_t nbPairs)
+    {
+        m_manager-&gt;onContact(pairHeader, pairs, nbPairs);
+    }
 
-    <span class="keyword">private</span>:
-        ExtImpactDamageManager*     m_manager;
-    };
+<span class="keyword">private</span>:
+    ExtImpactDamageManager*     m_manager;
+};
 </pre></div><p>
 Call <em>applyDamage()</em> when you want the buffered damage to be applied:<p>
 <div class="fragment"><pre class="fragment">impactManager-&gt;applyDamage();
 </pre></div><p>
-Also important to enable contact notification with custom filter shader for PxScene. <em>ImpactDamageManager</em> has a reference filter shader implementation which can be used for that:<p>
+<b>N.B.</b> for impact damage to work, you must enable contact notification with custom the filter shader for PxScene. <em>ExtImpactDamageManager</em> has a reference filter shader implementation which can be used for that:<p>
 <div class="fragment"><pre class="fragment">PxSceneDesc sceneDesc;
 sceneDesc.filterShader = ExtImpactDamageManager::FilterShader;
 </pre></div><p>
 <br>
- <h2><a class="anchor" name="ExtStressSolver">
-ExtStressSolver</a></h2>
-<b>Stress Solver</b> - is a reference implementation of stress propagation using Blast support graph.<h3><a class="anchor" name="Features">
-Features</a></h3>
-<ul>
-<li>Supports both static and dynamic actors</li><li>Propagates both linear and angular momentum</li><li>Graph complexity selection (reduces support graph to smaller size trade off speed and quality)</li><li>Apply stress damage on Blast Actor</li><li>Debug Render</li></ul>
-<h3><a class="anchor" name="Usage">
+ <h2><a class="anchor" name="extpxstresssolver">
+ExtPxStressSolver</a></h2>
+<b>Stress Solver</b> - this wrapper class uses <a class="el" href="pageextstress.html">Stress Solver Extension (NvBlastExtStress)</a> to apply stress calculations to an ExtPxFamily. See <a class="el" href="pageextstress.html">Stress Solver Extension (NvBlastExtStress)</a> for the details of the underlying stress solver.<h3><a class="anchor" name="pxstresssolverusage">
 Usage</a></h3>
-In order to use it instance stress solver by providing <em>ExtPxFamily:</em> <p>
-<div class="fragment"><pre class="fragment">ExtStressSolver* stressSolver = ExtStressSolver::create(family);
+In order to use it, instance an ExtPxStressSolver by providing <em>ExtPxFamily:</em> <p>
+<div class="fragment"><pre class="fragment">ExtPxStressSolver* stressSolver = ExtPxStressSolver::create(family);
 </pre></div><p>
 And then call update() every frame:<p>
 <div class="fragment"><pre class="fragment"><span class="keywordtype">bool</span> doDamage = <span class="keyword">true</span>; <span class="comment">// if you want to actually apply stress and damage actors</span>
 stressSolver-&gt;update(doDamage);
 </pre></div><p>
-By default it will apply scene gravity on static actors and centrifugal force on dynamic actors. Also applyImpulse(...) can be called for additional stress to apply:<p>
-<div class="fragment"><pre class="fragment">stressSolver-&gt;applyImpulse(actor, position, force);
+By default it will apply scene gravity on static actors and centrifugal force on dynamic actors.<p>
+The underlying ExtStressSolver can be accessed using ExtPxStressSolver::getSolver(). For example, to apply impulse to a particular actor, use applyImpulse(...) can be called for additional stress to apply:<p>
+<div class="fragment"><pre class="fragment">stressSolver-&gt;getSolver().addForce(actor, position, impulse);
+</pre></div><p>
+Finally, the stress solver (and its underlying ExtStressSolver) may be released using<p>
+<div class="fragment"><pre class="fragment">stressSolver-&gt;release();
 </pre></div><p>
-It fully utilizes the fact that it knows initial support graph structure and does maximum of processing in <em>create</em>(...) method calls. After that all actors split calls are synced internally quite fast and only the actual stress propagation takes most of computational time. Computational time is linearly proprtional to <em>bondIterationsPerFrame</em> setting. To fine tune look for balance between <em>bondIterationsPerFrame</em> and <em>graphReductionLevel</em> . The more bond iterations are set the more precise computation will be. The smaller graph allows to make higher fidelity computations witihing the same bond iterations per frame (same time spent), but actual cracks (damaged bonds) will be more sparsed as the result.<p>
 <br>
  <h2><a class="anchor" name="ExtSync">
 ExtSync</a></h2>
-- 
cgit v1.2.3

