From d41654b469fa51870b5952c836c04d9da17f32d3 Mon Sep 17 00:00:00 2001 From: Anton Novoselov Date: Tue, 8 Aug 2017 20:14:22 +0300 Subject: Updated to CL 22627414: * docs updates * authoring fixes * stress solver crash fixes --- .../files/_nv_blast_ext_authoring_8h-source.html | 16 +- ...last_ext_authoring_fracture_tool_8h-source.html | 72 +-- .../_nv_blast_ext_authoring_types_8h-source.html | 2 +- docs/api_docs/files/annotated.html | 18 - ...lass_nv_1_1_blast_1_1_blast_bond_generator.html | 4 +- ...class_nv_1_1_blast_1_1_convex_mesh_builder.html | 2 +- .../class_nv_1_1_blast_1_1_ext_px_manager.html | 2 +- ...ass_nv_1_1_blast_1_1_fracture_tool-members.html | 2 +- .../class_nv_1_1_blast_1_1_fracture_tool.html | 25 +- .../class_nv_1_1_blast_1_1_i_fbx_file_reader.html | 2 +- .../class_nv_1_1_blast_1_1_i_mesh_file_reader.html | 4 +- ...s_nv_1_1_blast_1_1_json_collision_exporter.html | 2 +- .../files/class_nv_1_1_blast_1_1_tk_framework.html | 4 +- docs/api_docs/files/classes.html | 34 +- docs/api_docs/files/files.html | 18 - docs/api_docs/files/functions.html | 21 +- docs/api_docs/files/functions_0x62.html | 2 - docs/api_docs/files/functions_0x63.html | 27 +- docs/api_docs/files/functions_0x64.html | 15 +- docs/api_docs/files/functions_0x65.html | 12 +- docs/api_docs/files/functions_0x66.html | 35 +- docs/api_docs/files/functions_0x67.html | 28 +- docs/api_docs/files/functions_0x68.html | 2 - docs/api_docs/files/functions_0x69.html | 29 +- docs/api_docs/files/functions_0x6a.html | 2 - docs/api_docs/files/functions_0x6c.html | 4 - docs/api_docs/files/functions_0x6d.html | 21 +- docs/api_docs/files/functions_0x6e.html | 2 - docs/api_docs/files/functions_0x6f.html | 19 - docs/api_docs/files/functions_0x70.html | 16 +- docs/api_docs/files/functions_0x71.html | 2 - docs/api_docs/files/functions_0x72.html | 22 +- docs/api_docs/files/functions_0x73.html | 21 +- docs/api_docs/files/functions_0x74.html | 30 +- docs/api_docs/files/functions_0x75.html | 19 +- docs/api_docs/files/functions_0x76.html | 6 +- docs/api_docs/files/functions_0x77.html | 2 - docs/api_docs/files/functions_0x78.html | 2 - docs/api_docs/files/functions_0x79.html | 2 - docs/api_docs/files/functions_0x7a.html | 2 - docs/api_docs/files/functions_0x7e.html | 4 - docs/api_docs/files/functions_enum.html | 4 - docs/api_docs/files/functions_eval.html | 6 - docs/api_docs/files/functions_func.html | 6 +- docs/api_docs/files/functions_func_0x62.html | 2 - docs/api_docs/files/functions_func_0x63.html | 20 +- docs/api_docs/files/functions_func_0x64.html | 8 - docs/api_docs/files/functions_func_0x65.html | 4 - docs/api_docs/files/functions_func_0x66.html | 15 - docs/api_docs/files/functions_func_0x67.html | 36 +- docs/api_docs/files/functions_func_0x69.html | 21 - docs/api_docs/files/functions_func_0x6a.html | 2 - docs/api_docs/files/functions_func_0x6c.html | 4 - docs/api_docs/files/functions_func_0x6e.html | 2 - docs/api_docs/files/functions_func_0x6f.html | 19 - docs/api_docs/files/functions_func_0x70.html | 16 +- docs/api_docs/files/functions_func_0x72.html | 32 +- docs/api_docs/files/functions_func_0x73.html | 12 +- docs/api_docs/files/functions_func_0x74.html | 11 +- docs/api_docs/files/functions_func_0x75.html | 2 - docs/api_docs/files/functions_func_0x76.html | 6 +- docs/api_docs/files/functions_func_0x77.html | 2 - docs/api_docs/files/functions_func_0x7a.html | 2 - docs/api_docs/files/functions_func_0x7e.html | 4 - docs/api_docs/files/functions_vars.html | 2 - docs/api_docs/files/functions_vars_0x62.html | 2 - docs/api_docs/files/functions_vars_0x63.html | 2 - docs/api_docs/files/functions_vars_0x64.html | 2 - docs/api_docs/files/functions_vars_0x65.html | 2 - docs/api_docs/files/functions_vars_0x66.html | 2 - docs/api_docs/files/functions_vars_0x67.html | 2 - docs/api_docs/files/functions_vars_0x68.html | 2 - docs/api_docs/files/functions_vars_0x69.html | 2 - docs/api_docs/files/functions_vars_0x6a.html | 2 - docs/api_docs/files/functions_vars_0x6c.html | 2 - docs/api_docs/files/functions_vars_0x6d.html | 21 +- docs/api_docs/files/functions_vars_0x6e.html | 2 - docs/api_docs/files/functions_vars_0x6f.html | 2 - docs/api_docs/files/functions_vars_0x70.html | 2 - docs/api_docs/files/functions_vars_0x71.html | 2 - docs/api_docs/files/functions_vars_0x72.html | 2 - docs/api_docs/files/functions_vars_0x73.html | 2 - docs/api_docs/files/functions_vars_0x74.html | 2 - docs/api_docs/files/functions_vars_0x75.html | 21 +- docs/api_docs/files/functions_vars_0x76.html | 2 - docs/api_docs/files/functions_vars_0x77.html | 2 - docs/api_docs/files/functions_vars_0x78.html | 2 - docs/api_docs/files/functions_vars_0x79.html | 2 - docs/api_docs/files/functions_vars_0x7a.html | 2 - docs/api_docs/files/globals.html | 113 ----- docs/api_docs/files/globals_defs.html | 124 +---- docs/api_docs/files/globals_func.html | 2 - docs/api_docs/files/hierarchy.html | 21 - docs/api_docs/files/namespace_nv_1_1_blast.html | 533 --------------------- docs/api_docs/files/namespacemembers.html | 34 -- docs/api_docs/files/namespacemembers_func.html | 34 -- docs/api_docs/files/namespaces.html | 1 - docs/api_docs/files/pageauthoring.html | 6 +- docs/api_docs/files/pagedefinitions.html | 2 +- docs/api_docs/files/pageextapi.html | 4 +- docs/api_docs/files/pageextauthoring.html | 22 +- docs/api_docs/files/pageextimport.html | 4 +- docs/api_docs/files/pageextphysx.html | 42 +- docs/api_docs/files/pageextpxserialization.html | 6 +- docs/api_docs/files/pageextserialization.html | 15 +- docs/api_docs/files/pageextstress.html | 26 +- docs/api_docs/files/pageexttkserialization.html | 6 +- docs/api_docs/files/pageglobalsapi.html | 2 +- docs/api_docs/files/pagehlapi.html | 316 ++++++------ docs/api_docs/files/pageimporter.html | 6 +- docs/api_docs/files/pageintroduction.html | 2 +- docs/api_docs/files/pagellapi.html | 242 +++++----- docs/api_docs/files/pagesampleassetviewer.html | 16 +- docs/api_docs/files/pagetools.html | 2 +- .../struct_nv_1_1_blast_1_1_authoring_result.html | 6 +- docs/api_docs/files/tree.html | 100 +--- 116 files changed, 600 insertions(+), 1965 deletions(-) (limited to 'docs/api_docs') diff --git a/docs/api_docs/files/_nv_blast_ext_authoring_8h-source.html b/docs/api_docs/files/_nv_blast_ext_authoring_8h-source.html index f3a3f29..c015558 100644 --- a/docs/api_docs/files/_nv_blast_ext_authoring_8h-source.html +++ b/docs/api_docs/files/_nv_blast_ext_authoring_8h-source.html @@ -58,16 +58,16 @@ 00037 class PxPhysicsInsertionCallback; 00038 } 00039 -00040 namespace Nv +00040 namespace Nv 00041 { -00042 namespace Blast +00042 namespace Blast 00043 { -00044 class Mesh; -00045 class VoronoiSitesGenerator; -00046 class FractureTool; -00047 class ConvexMeshBuilder; -00048 class BlastBondGenerator; -00049 class MeshCleaner; +00044 class Mesh; +00045 class VoronoiSitesGenerator; +00046 class FractureTool; +00047 class ConvexMeshBuilder; +00048 class BlastBondGenerator; +00049 class MeshCleaner; 00050 } 00051 } 00052 diff --git a/docs/api_docs/files/_nv_blast_ext_authoring_fracture_tool_8h-source.html b/docs/api_docs/files/_nv_blast_ext_authoring_fracture_tool_8h-source.html index d1baa4e..7d458f3 100644 --- a/docs/api_docs/files/_nv_blast_ext_authoring_fracture_tool_8h-source.html +++ b/docs/api_docs/files/_nv_blast_ext_authoring_fracture_tool_8h-source.html @@ -110,7 +110,7 @@ 00134 00141 virtual void clusteredSitesGeneration(uint32_t numberOfClusters, uint32_t sitesPerCluster, float clusterRadius) = 0; 00142 -00153 virtual void radialPattern(const physx::PxVec3& center, const physx::PxVec3& normal, float radius, int32_t angularSteps, int32_t radialSteps, float angleOffset = 0.0f, float variability = 0.0f) = 0; +00153 virtual void radialPattern(const physx::PxVec3& center, const physx::PxVec3& normal, float radius, int32_t angularSteps, int32_t radialSteps, float angleOffset = 0.0f, float variability = 0.0f) = 0; 00154 00161 virtual void generateInSphere(const uint32_t count, const float radius, const physx::PxVec3& center) = 0; 00166 virtual void setStencil(const Mesh* stencil) = 0; @@ -139,44 +139,44 @@ 00217 00226 virtual int32_t voronoiFracturing(uint32_t chunkId, uint32_t cellCount, const physx::PxVec3* cellPoints, bool replaceChunk) = 0; 00227 -00238 virtual int32_t voronoiFracturing(uint32_t chunkId, uint32_t cellCount, const physx::PxVec3* cellPoints, const physx::PxVec3& scale, bool replaceChunk) = 0; -00239 +00239 virtual int32_t voronoiFracturing(uint32_t chunkId, uint32_t cellCount, const physx::PxVec3* cellPoints, const physx::PxVec3& scale, const physx::PxQuat& rotation, bool replaceChunk) = 0; 00240 -00251 virtual int32_t slicing(uint32_t chunkId, SlicingConfiguration conf, bool replaceChunk, RandomGeneratorBase* rnd) = 0; -00252 +00241 +00252 virtual int32_t slicing(uint32_t chunkId, SlicingConfiguration conf, bool replaceChunk, RandomGeneratorBase* rnd) = 0; 00253 -00257 virtual void finalizeFracturing() = 0; -00258 -00259 virtual uint32_t getChunkCount() const = 0; -00260 -00264 virtual const ChunkInfo& getChunkInfo(int32_t chunkIndex) = 0; -00265 -00273 virtual float getMeshOverlap(const Mesh& meshA, const Mesh& meshB) = 0; -00274 -00281 virtual uint32_t getBaseMesh(int32_t chunkIndex, Triangle*& output) = 0; -00282 -00288 virtual int32_t getChunkIndex(int32_t chunkId) = 0; -00289 -00295 virtual int32_t getChunkId(int32_t chunkIndex) = 0; -00296 -00302 virtual int32_t getChunkDepth(int32_t chunkId) = 0; -00303 -00310 virtual uint32_t getChunksIdAtDepth(uint32_t depth, int32_t*& chunkIds) = 0; -00311 +00254 +00258 virtual void finalizeFracturing() = 0; +00259 +00260 virtual uint32_t getChunkCount() const = 0; +00261 +00265 virtual const ChunkInfo& getChunkInfo(int32_t chunkIndex) = 0; +00266 +00274 virtual float getMeshOverlap(const Mesh& meshA, const Mesh& meshB) = 0; +00275 +00282 virtual uint32_t getBaseMesh(int32_t chunkIndex, Triangle*& output) = 0; +00283 +00289 virtual int32_t getChunkIndex(int32_t chunkId) = 0; +00290 +00296 virtual int32_t getChunkId(int32_t chunkIndex) = 0; +00297 +00303 virtual int32_t getChunkDepth(int32_t chunkId) = 0; +00304 +00311 virtual uint32_t getChunksIdAtDepth(uint32_t depth, int32_t*& chunkIds) = 0; 00312 -00322 virtual uint32_t getBufferedBaseMeshes(Vertex*& vertexBuffer, uint32_t*& indexBuffer, uint32_t*& indexBufferOffsets) = 0; -00323 -00328 virtual void setRemoveIslands(bool isRemoveIslands) = 0; -00329 -00335 virtual int32_t islandDetectionAndRemoving(int32_t chunkId) = 0; -00336 -00341 virtual bool isMeshContainOpenEdges(const Mesh* input) = 0; -00342 }; -00343 -00344 } // namespace Blast -00345 } // namespace Nv -00346 -00347 #endif // ifndef NVBLASTAUTHORINGFRACTURETOOL_H +00313 +00323 virtual uint32_t getBufferedBaseMeshes(Vertex*& vertexBuffer, uint32_t*& indexBuffer, uint32_t*& indexBufferOffsets) = 0; +00324 +00329 virtual void setRemoveIslands(bool isRemoveIslands) = 0; +00330 +00336 virtual int32_t islandDetectionAndRemoving(int32_t chunkId) = 0; +00337 +00342 virtual bool isMeshContainOpenEdges(const Mesh* input) = 0; +00343 }; +00344 +00345 } // namespace Blast +00346 } // namespace Nv +00347 +00348 #endif // ifndef NVBLASTAUTHORINGFRACTURETOOL_H diff --git a/docs/api_docs/files/class_nv_1_1_blast_1_1_fracture_tool.html b/docs/api_docs/files/class_nv_1_1_blast_1_1_fracture_tool.html index b416953..20f2f1a 100644 --- a/docs/api_docs/files/class_nv_1_1_blast_1_1_fracture_tool.html +++ b/docs/api_docs/files/class_nv_1_1_blast_1_1_fracture_tool.html @@ -67,7 +67,7 @@ virtual int32_t slicing (uint32_t chunkId, SlicingConfiguration conf, bool replaceChunk, RandomGeneratorBase *rnd)=0 -virtual int32_t voronoiFracturing (uint32_t chunkId, uint32_t cellCount, const physx::PxVec3 *cellPoints, const physx::PxVec3 &scale, bool replaceChunk)=0 +virtual int32_t voronoiFracturing (uint32_t chunkId, uint32_t cellCount, const physx::PxVec3 *cellPoints, const physx::PxVec3 &scale, const physx::PxQuat &rotation, bool replaceChunk)=0 virtual int32_t voronoiFracturing (uint32_t chunkId, uint32_t cellCount, const physx::PxVec3 *cellPoints, bool replaceChunk)=0 @@ -164,7 +164,7 @@ Creates resulting fractured mesh geometry from intermediate format Get chunk base mesh
Parameters:
- +
[in] chunkIndex Chunk index
[out] output Array of triangles to be filled
[out] output Array of triangles to be filled
Returns:
number of triangles in base mesh
@@ -205,9 +205,9 @@ Get chunk base mesh
Parameters:

Get result geometry without noise as vertex and index buffers, where index buffers contain series of triplets which represent triangles.

Parameters:
- - - + + +
[out] vertexBuffer Array of vertices to be filled
[out] indexBuffer Array of indices to be filled
[out] indexBufferOffsets Array of offsets in indexBuffer for each base mesh. Contains getChunkCount() + 1 elements. Last one is indexBuffer size
[out] vertexBuffer Array of vertices to be filled
[out] indexBuffer Array of indices to be filled
[out] indexBufferOffsets Array of offsets in indexBuffer for each base mesh. Contains getChunkCount() + 1 elements. Last one is indexBuffer size
Returns:
Number of vertices in vertexBuffer
@@ -612,7 +612,7 @@ Fractures specified chunk with slicing method.
Parameters:

- +

@@ -640,6 +640,12 @@ Fractures specified chunk with slicing method.
Parameters:const physx::PxVec3 & 
+ + + + + + @@ -659,9 +665,10 @@ Fractures specified chunk with slicing method.
Parameters:
Parameters:
scale,
const physx::PxQuat &  rotation,
- - + + +
[in] chunkId Chunk to fracture
[in] cellPoints Array of voronoi sites
[in] cellPoints Array of voronoi sites
[in] cellPoints Array of voronoi sites
[in] cellPoints Array of voronoi sites
[in] scale Voronoi cells scaling factor
[in] rotation Voronoi cells rotation. Has no effect without cells scale factor
[in] replaceChunk if 'true', newly generated chunks will replace source chunk, if 'false', newly generated chunks will be at next depth level, source chunk will be parent for them. Case replaceChunk == true && chunkId == 0 considered as wrong input parameters
@@ -710,7 +717,7 @@ Fractures specified chunk with voronoi method. Cells can be scaled along x,y,z a Fractures specified chunk with voronoi method.
Parameters:
- +
[in] chunkId Chunk to fracture
[in] cellPoints Array of voronoi sites
[in] cellPoints Array of voronoi sites
[in] replaceChunk if 'true', newly generated chunks will replace source chunk, if 'false', newly generated chunks will be at next depth level, source chunk will be parent for them. Case replaceChunk == true && chunkId == 0 considered as wrong input parameters
diff --git a/docs/api_docs/files/class_nv_1_1_blast_1_1_i_fbx_file_reader.html b/docs/api_docs/files/class_nv_1_1_blast_1_1_i_fbx_file_reader.html index 59c1c08..1656234 100644 --- a/docs/api_docs/files/class_nv_1_1_blast_1_1_i_fbx_file_reader.html +++ b/docs/api_docs/files/class_nv_1_1_blast_1_1_i_fbx_file_reader.html @@ -84,7 +84,7 @@ Return number of bones in fbx file Retrieve bone influence if it exist
Note:
User should call NVBLAST_FREE for out when it not needed anymore
Parameters:
- +
[out] out Array of bone influences.
[out] out Array of bone influences.
Returns:
Number of bones influences (boneCount)
diff --git a/docs/api_docs/files/class_nv_1_1_blast_1_1_i_mesh_file_reader.html b/docs/api_docs/files/class_nv_1_1_blast_1_1_i_mesh_file_reader.html index d6d9171..095724e 100644 --- a/docs/api_docs/files/class_nv_1_1_blast_1_1_i_mesh_file_reader.html +++ b/docs/api_docs/files/class_nv_1_1_blast_1_1_i_mesh_file_reader.html @@ -98,8 +98,8 @@ An interface for Blast mesh Retrieve collision geometry if it exist
Note:
User should call NVBLAST_FREE for hulls and hullsOffset when it not needed anymore
Parameters:
- - + +
[out] hullsOffset Array of hull offsets for hulls array. The size is meshCount + 1.
[out] hulls Array of hull. The first i-th mesh hull: hulls[hullsOffset[i]]. The size is written to hullsOffset[meshCount]
[out] hullsOffset Array of hull offsets for hulls array. The size is meshCount + 1.
[out] hulls Array of hull. The first i-th mesh hull: hulls[hullsOffset[i]]. The size is written to hullsOffset[meshCount]
Returns:
Number of meshes (meshCount)
diff --git a/docs/api_docs/files/class_nv_1_1_blast_1_1_json_collision_exporter.html b/docs/api_docs/files/class_nv_1_1_blast_1_1_json_collision_exporter.html index 46e0a2c..ce3f3af 100644 --- a/docs/api_docs/files/class_nv_1_1_blast_1_1_json_collision_exporter.html +++ b/docs/api_docs/files/class_nv_1_1_blast_1_1_json_collision_exporter.html @@ -97,7 +97,7 @@ Serializes collision geometry to JSON format.

Constructor & Destruct Method creates file with given path and serializes given array of arrays of convex hulls to it in JSON format.
Parameters:
- +
[in] path Output file path
[in] hulls Array of arrays of convex hull descriptors. Each array contain array of convex hulls for chunk (hulls[0] - convexes for chunk 0, etc.)
[in] hulls Array of arrays of convex hull descriptors. Each array contain array of convex hulls for chunk (hulls[0] - convexes for chunk 0, etc.)
diff --git a/docs/api_docs/files/class_nv_1_1_blast_1_1_tk_framework.html b/docs/api_docs/files/class_nv_1_1_blast_1_1_tk_framework.html index 7238669..ca47d0d 100644 --- a/docs/api_docs/files/class_nv_1_1_blast_1_1_tk_framework.html +++ b/docs/api_docs/files/class_nv_1_1_blast_1_1_tk_framework.html @@ -486,9 +486,9 @@ This is a convenience wrapper for the low-level NvBlastReorderAssetDescChunks fu This function may modify both the chunkDescs and bondDescs array, since rearranging chunk descriptors requires re-indexing within the bond descriptors.

Parameters:
- + - + diff --git a/docs/api_docs/files/classes.html b/docs/api_docs/files/classes.html index 9807d7c..b9c3d81 100644 --- a/docs/api_docs/files/classes.html +++ b/docs/api_docs/files/classes.html @@ -20,26 +20,24 @@
-

Class Index

A | B | C | D | E | F | H | I | J | L | M | N | P | R | S | T | V

+

Class Index

A | B | C | E | F | I | J | L | M | N | P | R | S | T | V

[in] chunkDescs Array of chunk descriptors of size chunkCount. It will be updated accordingly.
[in] chunkDescs Array of chunk descriptors of size chunkCount. It will be updated accordingly.
[in] chunkCount The number of chunk descriptors.
[in] bondDescs Array of bond descriptors of size chunkCount. It will be updated accordingly.
[in] bondDescs Array of bond descriptors of size chunkCount. It will be updated accordingly.
[in] bondCount The number of bond descriptors.
[in] chunkReorderMap If not NULL, must be a pointer to a uint32_t array of size desc.chunkCount. Maps old chunk indices to the reordered chunk indices.
[in] keepBondNormalChunkOrder If true, bond normals will be flipped if their chunk index order was reveresed by the reorder map.
  A  
-
ExtPxAssetDesc::ChunkDesc (Nv::Blast)   
  H  
-
NvBlastExtAssetUtilsBondDesc   SlicingConfiguration (Nv::Blast)   
Allocator (Nv::Blast)   ExtPxAssetDesc::SubchunkDesc (Nv::Blast)   HashMap (Nv::Blast)   NvBlastExtMaterial   
  T  
-
AllocatorCallback (Nv::Blast)   ExtPxChunk (Nv::Blast)   HashSet (Nv::Blast)   NvBlastExtRadialDamageDesc   Time (Nv::Blast)   
ApexImporterConfig (Nv::Blast::ApexImporter)   ExtPxFamily (Nv::Blast)   
  I  
-
NvBlastExtSegmentRadialDamageDesc   TkActor (Nv::Blast)   
ApexImportTool (Nv::Blast::ApexImporter)   ExtPxFamilyDesc (Nv::Blast)   IFbxFileReader (Nv::Blast)   NvBlastExtShearDamageDesc   TkActorData (Nv::Blast)   
Array (Nv::Blast)   ExtPxListener (Nv::Blast)   IMeshFileReader (Nv::Blast)   NvBlastFamily   TkActorDesc (Nv::Blast)   
AuthoringResult (Nv::Blast)   ExtPxManager (Nv::Blast)   IMeshFileWriter (Nv::Blast)   NvBlastFractureBuffers   TkAsset (Nv::Blast)   
  B  
-
ExtPxObjectTypeID (Nv::Blast)   IndexDLink (Nv::Blast)   NvBlastGraphShaderActor   TkAssetDesc (Nv::Blast)   
BlastBondGenerator (Nv::Blast)   ExtPxShapeDescTemplate (Nv::Blast)   IndexDList (Nv::Blast)   NvBlastID   TkAssetJointDesc (Nv::Blast)   
BondGenerationConfig (Nv::Blast)   ExtPxSpawnSettings (Nv::Blast)   InlineArray (Nv::Blast)   NvBlastMessage   TkEvent (Nv::Blast)   
  C  
-
ExtPxStressSolver (Nv::Blast)   IteratorBase (Nv::Blast)   NvBlastProgramParams   TkEventListener (Nv::Blast)   
ChunkInfo (Nv::Blast)   ExtPxSubchunk (Nv::Blast)   
  J  
-
NvBlastSubgraphShaderActor   TkFamily (Nv::Blast)   
CollisionHull (Nv::Blast)   ExtSerialization (Nv::Blast)   JsonCollisionExporter (Nv::Blast)   NvBlastSupportGraph   TkFractureCommands (Nv::Blast)   
CollisionHull::HullPolygon (Nv::Blast)   ExtSerialization::BufferProvider (Nv::Blast)   
  L  
-
NvBlastTimers   TkFractureEvents (Nv::Blast)   
ConvexMeshBuilder (Nv::Blast)   ExtSerialization::EncodingID (Nv::Blast)   Less (Nv::Blast)   NvcBounds3   TkFramework (Nv::Blast)   
  D  
-
ExtStressSolver (Nv::Blast)   LListIt (Nv::Blast)   NvcMat33   TkGroup (Nv::Blast)   
DLink (Nv::Blast)   ExtStressSolver::DebugBuffer (Nv::Blast)   LlObjectTypeID (Nv::Blast)   NvcMat34   TkGroupDesc (Nv::Blast)   
DList (Nv::Blast)   ExtStressSolver::DebugLine (Nv::Blast)   
  M  
-
NvcMat44   TkGroupStats (Nv::Blast)   
DList::It (Nv::Blast)   ExtStressSolverSettings (Nv::Blast)   Mesh (Nv::Blast)   NvcPlane   TkGroupWorker (Nv::Blast)   
DListIt (Nv::Blast)   ExtSync (Nv::Blast)   MeshCleaner (Nv::Blast)   NvcQuat   TkIdentifiable (Nv::Blast)   
  E  
-
ExtSyncEvent (Nv::Blast)   
  N  
-
NvcTransform   TkJoint (Nv::Blast)   
Edge (Nv::Blast)   ExtSyncEventFamilySync (Nv::Blast)   NvBlastActor   NvcVec2   TkJointData (Nv::Blast)   
ErrorCallback (Nv::Blast)   ExtSyncEventFracture (Nv::Blast)   NvBlastActorDesc   NvcVec2i   TkJointDesc (Nv::Blast)   
ErrorCode (Nv::Blast)   ExtSyncEventInstance (Nv::Blast)   NvBlastActorSplitEvent   NvcVec3   TkJointUpdateEvent (Nv::Blast)   
ExporterMeshData (Nv::Blast)   ExtSyncEventPhysicsSync (Nv::Blast)   NvBlastAsset   NvcVec3i   TkObject (Nv::Blast)   
ExtCustomProfiler (Nv::Blast)   ExtSyncEventPhysicsSync::ActorData (Nv::Blast)   NvBlastAssetDesc   NvcVec4   TkObjectTypeID (Nv::Blast)   
ExtForceMode (Nv::Blast)   ExtSyncEventType (Nv::Blast)   NvBlastBond   NvcVec4i   TkSplitEvent (Nv::Blast)   
ExtGroupTaskManager (Nv::Blast)   
  F  
-
NvBlastBondDesc   
  P  
-
TkType (Nv::Blast)   
ExtImpactDamageManager (Nv::Blast)   Facet (Nv::Blast)   NvBlastBondFractureData   PlaneChunkIndexer (Nv::Blast)   TkTypeIndex (Nv::Blast)   
ExtImpactSettings (Nv::Blast)   FixedArray (Nv::Blast)   NvBlastChunk   ProfilerCallback (Nv::Blast)   Triangle (Nv::Blast)   
ExtProfileData (Nv::Blast)   FixedBitmap (Nv::Blast)   NvBlastChunkDesc   ProfilerDetail (Nv::Blast)   TriangleIndexed (Nv::Blast)   
ExtPxActor (Nv::Blast)   FixedBoolArray (Nv::Blast)   NvBlastChunkFractureData   
  R  
-
  V  
-
ExtPxActorDescTemplate (Nv::Blast)   FixedPriorityQueue (Nv::Blast)   NvBlastDamageProgram   RandomGeneratorBase (Nv::Blast)   Vertex (Nv::Blast)   
ExtPxAsset (Nv::Blast)   FractureTool (Nv::Blast)   NvBlastDataBlock   
  S  
-
VoronoiSitesGenerator (Nv::Blast)   
ExtPxAssetDesc (Nv::Blast)   

A | B | C | D | E | F | H | I | J | L | M | N | P | R | S | T | V

+ExtPxChunk (Nv::Blast)   IMeshFileReader (Nv::Blast)   NvBlastGraphShaderActor   TkActorData (Nv::Blast)   Allocator (Nv::Blast)   ExtPxFamily (Nv::Blast)   IMeshFileWriter (Nv::Blast)   NvBlastID   TkActorDesc (Nv::Blast)   AllocatorCallback (Nv::Blast)   ExtPxFamilyDesc (Nv::Blast)   
  J  
+NvBlastMessage   TkAsset (Nv::Blast)   ApexImporterConfig (Nv::Blast::ApexImporter)   ExtPxListener (Nv::Blast)   JsonCollisionExporter (Nv::Blast)   NvBlastProgramParams   TkAssetDesc (Nv::Blast)   ApexImportTool (Nv::Blast::ApexImporter)   ExtPxManager (Nv::Blast)   
  L  
+NvBlastSubgraphShaderActor   TkAssetJointDesc (Nv::Blast)   AuthoringResult (Nv::Blast)   ExtPxObjectTypeID (Nv::Blast)   LlObjectTypeID (Nv::Blast)   NvBlastSupportGraph   TkEvent (Nv::Blast)   
  B  
+ExtPxShapeDescTemplate (Nv::Blast)   
  M  
+NvBlastTimers   TkEventListener (Nv::Blast)   BlastBondGenerator (Nv::Blast)   ExtPxSpawnSettings (Nv::Blast)   Mesh (Nv::Blast)   NvcBounds3   TkFamily (Nv::Blast)   BondGenerationConfig (Nv::Blast)   ExtPxStressSolver (Nv::Blast)   MeshCleaner (Nv::Blast)   NvcMat33   TkFractureCommands (Nv::Blast)   
  C  
+ExtPxSubchunk (Nv::Blast)   
  N  
+NvcMat34   TkFractureEvents (Nv::Blast)   ChunkInfo (Nv::Blast)   ExtSerialization (Nv::Blast)   NvBlastActor   NvcMat44   TkFramework (Nv::Blast)   CollisionHull (Nv::Blast)   ExtSerialization::BufferProvider (Nv::Blast)   NvBlastActorDesc   NvcPlane   TkGroup (Nv::Blast)   CollisionHull::HullPolygon (Nv::Blast)   ExtSerialization::EncodingID (Nv::Blast)   NvBlastActorSplitEvent   NvcQuat   TkGroupDesc (Nv::Blast)   ConvexMeshBuilder (Nv::Blast)   ExtStressSolver (Nv::Blast)   NvBlastAsset   NvcTransform   TkGroupStats (Nv::Blast)   
  E  
+ExtStressSolver::DebugBuffer (Nv::Blast)   NvBlastAssetDesc   NvcVec2   TkGroupWorker (Nv::Blast)   Edge (Nv::Blast)   ExtStressSolver::DebugLine (Nv::Blast)   NvBlastBond   NvcVec2i   TkIdentifiable (Nv::Blast)   ErrorCallback (Nv::Blast)   ExtStressSolverSettings (Nv::Blast)   NvBlastBondDesc   NvcVec3   TkJoint (Nv::Blast)   ErrorCode (Nv::Blast)   ExtSync (Nv::Blast)   NvBlastBondFractureData   NvcVec3i   TkJointData (Nv::Blast)   ExporterMeshData (Nv::Blast)   ExtSyncEvent (Nv::Blast)   NvBlastChunk   NvcVec4   TkJointDesc (Nv::Blast)   ExtCustomProfiler (Nv::Blast)   ExtSyncEventFamilySync (Nv::Blast)   NvBlastChunkDesc   NvcVec4i   TkJointUpdateEvent (Nv::Blast)   ExtForceMode (Nv::Blast)   ExtSyncEventFracture (Nv::Blast)   NvBlastChunkFractureData   
  P  
+TkObject (Nv::Blast)   ExtGroupTaskManager (Nv::Blast)   ExtSyncEventInstance (Nv::Blast)   NvBlastDamageProgram   PlaneChunkIndexer (Nv::Blast)   TkObjectTypeID (Nv::Blast)   ExtImpactDamageManager (Nv::Blast)   ExtSyncEventPhysicsSync (Nv::Blast)   NvBlastDataBlock   ProfilerCallback (Nv::Blast)   TkSplitEvent (Nv::Blast)   ExtImpactSettings (Nv::Blast)   ExtSyncEventPhysicsSync::ActorData (Nv::Blast)   NvBlastExtAssetUtilsBondDesc   ProfilerDetail (Nv::Blast)   TkType (Nv::Blast)   ExtProfileData (Nv::Blast)   ExtSyncEventType (Nv::Blast)   NvBlastExtMaterial   
  R  
+TkTypeIndex (Nv::Blast)   ExtPxActor (Nv::Blast)   
  F  
+NvBlastExtRadialDamageDesc   RandomGeneratorBase (Nv::Blast)   Triangle (Nv::Blast)   ExtPxActorDescTemplate (Nv::Blast)   Facet (Nv::Blast)   NvBlastExtSegmentRadialDamageDesc   
  S  
+TriangleIndexed (Nv::Blast)   ExtPxAsset (Nv::Blast)   FractureTool (Nv::Blast)   NvBlastExtShearDamageDesc   SlicingConfiguration (Nv::Blast)   
  V  
+ExtPxAssetDesc (Nv::Blast)   
  I  
+NvBlastFamily   
  T  
+Vertex (Nv::Blast)   ExtPxAssetDesc::ChunkDesc (Nv::Blast)   IFbxFileReader (Nv::Blast)   NvBlastFractureBuffers   TkActor (Nv::Blast)   VoronoiSitesGenerator (Nv::Blast)   ExtPxAssetDesc::SubchunkDesc (Nv::Blast)   

A | B | C | E | F | I | J | L | M | N | P | R | S | T | V


Function Documentation

- -
-
-
-template<typename T >
- - - - - - - - - -
NV_INLINE T Nv::Blast::align16 ( value  )  [inline]
-
-
- -

-Utility function to align the given value to the next 16-byte boundary.

-Returns the aligned value. -

-

- -

-
- - - - - - - - - -
int32_t Nv::Blast::atomicDecrement (volatile int32_t *  val  ) 
-
-
- -

- -

-

- -

-
- - - - - - - - - -
int32_t Nv::Blast::atomicIncrement (volatile int32_t *  val  ) 
-
-
- -

- -

-

- -

-
-
-template<typename T >
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
void Nv::Blast::createIndexStartLookup (T *  lookup,
indexBase,
indexRange,
T *  indexSource,
indexCount,
indexByteStride 
) [inline]
-
-
- -

-Create a lookup table for data sorted by a templated index type.

-Note: when using this function with unsigned integer index types invalidIndex<T>() is treated as a value less than zero.

-On input:

-The indices must lie in the interval [indexBase, indexBase+indexRange].

-indexSource must point to the first index in the data.

-indexCount must be set to the number of indices in the data.

-indexByteStride must be set to the distance, in bytes, between subequent indices.

-lookup must point to a T array of size indexRange+2.

-On return:

-lookup will be filled such that:

-lookup[i] = the position of first data element with index (i + indexBase)

-lookup[indexRange+1] = indexCount

-The last (indexRange+1) element is used so that one may always determine the number of data elements with the given index using:

-count = lookup[i+1] - lookup[i]

-Note, if an index (i + indexBase) is not present in the data then, lookup[i+1] = lookup[i], so the count (above) will correctly be zero. In this case, the actual value of lookup[i] is irrelevant. -

-

- -

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NV_FORCE_INLINE uint32_t Nv::Blast::findClosestNode (const float  point[4],
const uint32_t  firstGraphNodeIndex,
const uint32_t *  familyGraphNodeIndexLinks,
const uint32_t *  adjacencyPartition,
const uint32_t *  adjacentNodeIndices,
const uint32_t *  adjacentBondIndices,
const NvBlastBond bonds,
const float *  bondHealths,
const uint32_t *  chunkIndices 
)
-
-
- -

-Find the closest node to point in the graph. Uses primarily distance to bond centroids. Slower compared to chunk based lookup but may yield better accuracy in some cases. Bond normals are expected to be directed from the lower to higher node index. Cannot be used for graph actors with only the world chunk in the graph.

-

Parameters:
- - - - - - - - - - -
[in] point the point to test against
[in] firstGraphNodeIndex the entry point for familyGraphNodeIndexLinks
[in] familyGraphNodeIndexLinks the list index links of the actor's graph
[in] adjacencyPartition the actor's SupportGraph adjacency partition
[in] adjacentNodeIndices the actor's SupportGraph adjacent node indices
[in] adjacentBondIndices the actor's SupportGraph adjacent bond indices
[in] assetBonds the actor's asset bonds
[in] bondHealths the actor's bond healths
[in] chunkIndices maps node index to chunk index in SupportGraph
-
-
Returns:
the index of the node closest to point
- -
-

- -

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NV_FORCE_INLINE uint32_t Nv::Blast::findClosestNode (const float  point[4],
const uint32_t  firstGraphNodeIndex,
const uint32_t *  familyGraphNodeIndexLinks,
const uint32_t *  adjacencyPartition,
const uint32_t *  adjacentNodeIndices,
const uint32_t *  adjacentBondIndices,
const NvBlastBond assetBonds,
const float *  bondHealths,
const NvBlastChunk assetChunks,
const float *  supportChunkHealths,
const uint32_t *  chunkIndices 
)
-
-
- -

-Find the closest node to point in the graph. Uses primarily distance to chunk centroids. Bond normals are expected to be directed from the lower to higher node index. Cannot be used for graph actors with only the world chunk in the graph.

-

Parameters:
- - - - - - - - - - - - -
[in] point the point to test against
[in] firstGraphNodeIndex the entry point for familyGraphNodeIndexLinks
[in] familyGraphNodeIndexLinks the list index links of the actor's graph
[in] adjacencyPartition the actor's SupportGraph adjacency partition
[in] adjacentNodeIndices the actor's SupportGraph adjacent node indices
[in] adjacentBondIndices the actor's SupportGraph adjacent bond indices
[in] assetBonds the actor's asset bonds
[in] bondHealths the actor's bond healths
[in] assetChunks the actor's asset chunks
[in] supportChunkHealths the actor's graph chunks healths
[in] chunkIndices maps node index to chunk index in SupportGraph
-
-
Returns:
the index of the node closest to point
- -
-

- -

-
-
-template<typename T >
- - - - - - - - -
NV_INLINE T Nv::Blast::invalidIndex (  )  [inline]
-
-
- -

-Set to invalid index. -

-

- -

-
-
-template<typename T >
- - - - - - - - - - - - - - - - - - - - - - - - -
void Nv::Blast::invertMap (T *  inverseMap,
const T *  map,
const T  size 
) [inline]
-
-
- -

-Creates the inverse of a map, such that inverseMap[map[i]] = i. Unmapped indices are set to invalidIndex<T>.

-

Parameters:
- - - - -
[out] inverseMap inverse map space of given size
[in] map original map of given size, unmapped entries must contain invalidIndex<T>
[in] size size of the involved maps
-
- -
-

- -

-
-
-template<typename T >
- - - - - - - - - -
NV_INLINE bool Nv::Blast::isInvalidIndex ( index  )  [inline]
-
-
- -

-Test for invalid index (max representable integer). -

-

@@ -758,68 +287,6 @@ Logging wrapper compatible with NvBlastLog.
See a Pass this function to LowLevel function calls in order to get logging into global ErrorCallback.

- -

-
-
-template<typename T >
- - - - - - - - - - - - - - - - - - -
NV_INLINE const void * Nv::Blast::pointerOffset (const void *  p,
ptrdiff_t  offset 
) [inline]
-
-
- -

- -

-

- -

-
-
-template<typename T >
- - - - - - - - - - - - - - - - - - -
NV_INLINE void * Nv::Blast::pointerOffset (void *  p,
ptrdiff_t  offset 
) [inline]
-
-
- -

-Offset void* pointer by 'offset' bytes helper-functions -

-

diff --git a/docs/api_docs/files/namespacemembers_func.html b/docs/api_docs/files/namespacemembers_func.html index 6ec7ae2..6f81ae8 100644 --- a/docs/api_docs/files/namespacemembers_func.html +++ b/docs/api_docs/files/namespacemembers_func.html @@ -30,42 +30,8 @@  

diff --git a/docs/api_docs/files/namespaces.html b/docs/api_docs/files/namespaces.html index ab54afd..4bbc17b 100644 --- a/docs/api_docs/files/namespaces.html +++ b/docs/api_docs/files/namespaces.html @@ -24,7 +24,6 @@ Nv Nv::Blast Nv::Blast::ApexImporter - Nv::Blast::VecMath nvidia nvidia::apex physx diff --git a/docs/api_docs/files/pageauthoring.html b/docs/api_docs/files/pageauthoring.html index 8777b4e..f3ff47e 100644 --- a/docs/api_docs/files/pageauthoring.html +++ b/docs/api_docs/files/pageauthoring.html @@ -20,9 +20,9 @@
-

AuthoringTool

The application AuthoringTool is a command-line asset authoring utility. It reads a file containing a single graphics mesh (currently .fbx and .obj format are supported in this tool), and fractures it according to the parameters given in the command line. User can configure output of tool. It can save render mesh geometry to .fbx or .obj file.

-Additionally user can set how Blast data should be saved:

-1) BPXA-asset which incorporates Blast data and collision geometry for physics engine.

+

AuthoringTool

The application AuthoringTool is a command-line asset authoring utility. It reads a file containing a single graphics mesh (currently .fbx and .obj format are supported in this tool), and fractures it according to the parameters given in the command line. The user can configure the output of the tool. It can save render mesh geometry to .fbx or .obj files.

+Additionally, the user can choose how Blast™ data should be saved:

+1) BPXA-asset which incorporates Blast™ data and collision geometry for physics engine.

2) LL-asset which is Low Level asset data

3) Tk-asset which is Toolkit asset data

BPXA and .obj files may be consumed by the SampleAssetViewer.

diff --git a/docs/api_docs/files/pagedefinitions.html b/docs/api_docs/files/pagedefinitions.html index f771b06..69e419b 100644 --- a/docs/api_docs/files/pagedefinitions.html +++ b/docs/api_docs/files/pagedefinitions.html @@ -21,7 +21,7 @@

Definitions

    -
  • exact coverage: the condition that a walk from any leaf chunk to its ancestor root chunk will always encounter exactly one support chunk
  • family: the memory allocated when an asset is instanced into its initial set of actors, and all descendent actors formed from fracturing the initial set, recursively
  • root chunk: a chunk with no parent
  • leaf chunk: a chunk with no children
  • lower-support chunk: a chunk that is either a support or subsupport chunk
  • subsupport chunk: a chunk that is descended from a support chunk
  • supersupport chunk: a chunk that is the ancestor of a support chunk
  • support chunk: a chunk that is represented in the support graph
  • upper-support chunk: a chunk that is either a support or supersupport chunk
+
  • exact coverage: the condition that a walk from any leaf chunk to its ancestor root chunk will always encounter exactly one support chunk
  • family: the memory allocated when an asset is instanced into its initial set of actors, and all descendant actors formed from fracturing the initial set, recursively
  • root chunk: a chunk with no parent
  • leaf chunk: a chunk with no children
  • lower-support chunk: a chunk that is either a support or subsupport chunk
  • subsupport chunk: a chunk that is descended from a support chunk
  • supersupport chunk: a chunk that is the ancestor of a support chunk
  • support chunk: a chunk that is represented in the support graph
  • upper-support chunk: a chunk that is either a support or supersupport chunk

  • diff --git a/docs/api_docs/files/pageextapi.html b/docs/api_docs/files/pageextapi.html index d2da64d..756752f 100644 --- a/docs/api_docs/files/pageextapi.html +++ b/docs/api_docs/files/pageextapi.html @@ -20,7 +20,7 @@
    -

    Extensions (NvBlastExt)

    These are the current Blast extensions:
    +

    Extensions (NvBlastExt)

    These are the current Blast™ extensions:

    Damage Shaders (NvBlastExtShaders) - Standard damage shaders (radial, shear, line segment) which can be used in NvBlast and NvBlastTk damage functions.

    @@ -40,7 +40,7 @@
    ExtPhysX Serialization (NvBlastExtPxSerialization) - This module contains serializers for ExtPhysX objects. Use in conjunction with ExtSerialization.

    - PhysX Extensions (NvBlastExtPhysX) - A reference implementation of a physics manager, using the PhysX SDK. Creates and manages actors and joints, and handles impact damage and uses the stress solver (ExtStress) to handle stress calculations.
    + PhysX™ Extensions (NvBlastExtPhysX) - A reference implementation of a physics manager, using the PhysX™ SDK. Creates and manages actors and joints, and handles impact damage and uses the stress solver (ExtStress) to handle stress calculations.

    To use them, include the appropriate headers in include/extensions (each extension will describe which headers are necessary), and link to the desired NvBlastExt*{config}{arch} library in the lib folder. Here, config is the usual DEBUG/CHECKED/PROFILE (or nothing for release), and {arch} distinguishes achitecture, if needed (such as _x86 or _x64).

    diff --git a/docs/api_docs/files/pageextauthoring.html b/docs/api_docs/files/pageextauthoring.html index 85cd03b..19e6f8e 100644 --- a/docs/api_docs/files/pageextauthoring.html +++ b/docs/api_docs/files/pageextauthoring.html @@ -21,36 +21,36 @@

    Asset Authoring (NvBlastExtAuthoring)

    The Authoring extension provides tools for creation of a Blast™ asset from a provided mesh.

    -There are three tools for creation Blast asset.

    -First one is FractureTool (see NvBlastExtAuthoringFractureTool.h) which is used to fracture an input mesh. It supports Voronoi fracturing and also simple slicing. Internal surfaces of output chunks can be tesselated and noise can be applied to them. The slicing method supports slicing with a noisy slicing surface, which allows the creation of a jagged slicing line. Noisy slicing is switched on by setting a non-zero noise amplitude in slicing parameters (Nv::Blast::SlicingConfiguration).

    +There are four tools for creation of Blast™ assets.


    FractureTool

    -Nv::Blast::FractureTool supports two types of output:

    +Nv::Blast::FractureTool (see NvBlastExtAuthoringFractureTool.h) is used to fracture an input mesh. It supports Voronoi fracturing and also simple slicing. Internal surfaces of output chunks can be tesselated and noise can be applied to them. The slicing method supports slicing with a noisy slicing surface, which allows the creation of a jagged slicing line. Noisy slicing is switched on by setting a non-zero noise amplitude in slicing parameters (Nv::Blast::SlicingConfiguration).

    +FractureTool supports two types of output:

    1) Array of triangles - the tool fills provided array with triangles of chunk, ID of chunk should be provided.

    -2) Buffered output - tool fills provided array with vertices, and another array of arrays with indices. Indices form triplets of vertices of triangle.

    +2) Buffered output - the tool fills provided array with vertices, and another array of arrays with indices. Indices form triplets of vertices of triangle.


    ConvexMeshBuilder

    -Nv::Blast::ConvexMeshBuilder is tool for creation collision geometry for physics engine. It recieves mesh vertices, and returns convex hull of that vertices. If creation of convex hull fails, tool creates collision geometry as a bounding box of provided vertices.

    -Tool provides method to trim convex hulls against each other. It can be used along with noisy slicing to avoid "explosive" behavior due to penetration of neighboor collision hulls into each other. As a drawback penetration of render meshes into each other is possible due to trimmed collision geometry.

    +Nv::Blast::ConvexMeshBuilder is a tool for creation of collision geometry for physics engine. It recieves mesh vertices, and returns the convex hull of those vertices. If creation of a convex hull fails, the tool creates collision geometry as a bounding box of provided vertices.

    +The tool provides a method to trim convex hulls against each other. It can be used along with noisy slicing to avoid "explosive" behavior due to penetration of neighboring collision hulls into each other. As a drawback, penetration of render meshes into each other is possible due to trimmed collision geometry.


    BondGenerator

    -Nv::Blast::BlastBondGenerator tool for creation Blast Bond descriptors from provided geometry data. It has separate method which is optimized for working FractureTool.
    int32_t Nv::Blast::BlastBondGenerator::buildDescFromInternalFracture(FractureTool* tool, const std::vector<bool>& chunkIsSupport, std::vector<NvBlastBondDesc>& resultBondDescs, std::vector<NvBlastChunkDesc>& resultChunkDescriptors);
    +Nv::Blast::BlastBondGenerator is a tool for creation of Blast™ Bond descriptors from provided geometry data. It has separate a method which is optimized for working FractureTool. 
    int32_t Nv::Blast::BlastBondGenerator::buildDescFromInternalFracture(FractureTool* tool, const std::vector<bool>& chunkIsSupport, std::vector<NvBlastBondDesc>& resultBondDescs, std::vector<NvBlastChunkDesc>& resultChunkDescriptors);
     

    -Other methods can work with prefractured mesh created in Third party tool, and can be used for converting prefractured models to Blast assets.

    +Other methods can work with prefractured meshes created in Third party tools, and can be used for converting prefractured models to Blast™ assets.

    Nv::Blast::BlastBondGenerator supports two modes of NvBlastBond data generation:

    1) Exact - in this mode exact common surface between chunks is found and considered as interface between them. Exact normal, area and centroid are computed.

    -2) Average - this mode uses approximations of interface, and can be used for gathering NvBlastBond data for assets, where chunks penetrate each other, e.g. chunks with noise.

    +2) Average - this mode uses approximations of the interface, and can be used for gathering NvBlastBond data for assets, where chunks penetrate each other, e.g. chunks with noise.


    MeshCleaner

    -Nv::Blast::MeshCleaner can be used to remove self intersections and open edges in interior of mesh, making it more likely to fracture well.

    +Nv::Blast::MeshCleaner can be used to remove self intersections and open edges in the interior of a mesh, making it more likely to fracture well.

    To use it, create a MeshCleaner using

    -Given an Nv::Blast::Mesh called "mesh," simply call

    +Given an Nv::Blast::Mesh called "mesh", simply call

    Nv::Blast::Mesh* newMesh = cleaner->cleanMesh(mesh);
     

    If successful, newMesh will be a valid pointer to the cleaned mesh. Otherwise, newMesh will be NULL.

    diff --git a/docs/api_docs/files/pageextimport.html b/docs/api_docs/files/pageextimport.html index 783c516..f7f24de 100644 --- a/docs/api_docs/files/pageextimport.html +++ b/docs/api_docs/files/pageextimport.html @@ -29,8 +29,8 @@ This tool supports two bond generation modes and can be configured by providing: }

    1) EXACT - Importer tries to find triangles from two chunks which lay in common surface. If such triangles are found, their intersections are considered as the interface.

    -2) FORCED - Bond creation is forced no matter how far chunks from each other. Interface parameters are approximated.

    -Nv::Blast::ApexImporter::ApexImportTool can be itinialized by providing ApexSDK and ModuleDestructible, or they can be created internally.

    +2) FORCED - Bond creation is forced no matter how far chunks are from each other. Interface parameters are approximated.

    +Nv::Blast::ApexImporter::ApexImportTool can be initialized by providing ApexSDK and ModuleDestructible, or they can be created internally.

    If ApexSDK and ModuleDestructible were provided, they are not freed when Nv::Blast::ApexImporter::~ApexImportTool() is called.

    diff --git a/docs/api_docs/files/pageextphysx.html b/docs/api_docs/files/pageextphysx.html index b1ee6ba..85ee427 100644 --- a/docs/api_docs/files/pageextphysx.html +++ b/docs/api_docs/files/pageextphysx.html @@ -1,6 +1,6 @@ - NVIDIA(R) Blast(R) SDK 1.1 API Reference: PhysX Extensions (NvBlastExtPhysX) + NVIDIA(R) Blast(R) SDK 1.1 API Reference: PhysX&tm; Extensions (NvBlastExtPhysX) @@ -20,21 +20,21 @@
    -

    PhysX Extensions (NvBlastExtPhysX)

    NvBlastExtPhysX contains classes for easier use of Blast Toolkit with the PhysX SDK. There are 3 of them:
      -
    • ExtPxManager: Manager to keep Blast Actors in sync with PhysX actors.
    • ExtImpactDamageManager: Manager to collect and apply impact damage caused by collision in PhysX Scene.
    • ExtPxStressSolver: Stress Solver to propagate stress through support graph and apply it as damage to Blast actors.
    +

    PhysX™ Extensions (NvBlastExtPhysX)

    NvBlastExtPhysX contains classes for easier use of Blast™ Toolkit with the PhysX™ SDK. There are 3 of them:
      +
    • ExtPxManager: Manager to keep Blast™ actors in sync with PhysX™ actors.
    • ExtImpactDamageManager: Manager to collect and apply impact damage caused by collision in PhysX™ scene.
    • ExtPxStressSolver: Stress Solver to propagate stress through support graph and apply it as damage to Blast™ actors.

    -This library also contains an extension for synchronizing Blast state:

      -
    • ExtSync - Utility for writing Blast state to a buffer, to be read by a client. This may be used for networking, for example.
    +This library also contains an extension for synchronizing Blast™ state:
      +
    • ExtSync - Utility for writing Blast™ state to a buffer, to be read by a client. This may be used for networking, for example.


    ExtPxManager

    -Physics Manager - is a reference implementation for keeping Blast Actors synced with PhysX actors. It's main job is to listen for TkFamily events and update PxScene (by adding and removing PxActors) accordingly.

    -In order to use it create an ExtPxManager. If we have a physx::PxPhysics object m_physics and a TkFramework m_tkFramework, use

    +Physics Manager - is a reference implementation for keeping Blast™ actors synced with PhysX™ actors. Its main job is to listen for TkFamily events and update PxScene (by adding and removing PxActors) accordingly.

    +In order to use it, create an ExtPxManager. If we have a physx::PxPhysics object m_physics and a TkFramework m_tkFramework, use

    ExtPxManager* pxManager = ExtPxManager::create(m_physics, m_tkFramework);
     

    -For every TkAsset prepare ExtPxAsset. Which contains TkAsset + 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 (isStatic 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.

    -To create a ExtPxFamily from an ExtPxAsset:

    +For every TkAsset prepare ExtPxAsset, which contains TkAsset + collection of physics geometry for every chunk. Every chunk can contain any number of subchunks, where each subchunk is basically a PxConvexMeshGeometry with transform. Also every chunk can be marked as static (isStatic flag). If an actor contains at least one static chunk in its support graph, it makes that actor kinematic (static). Otherwise the actor is dynamic. Having zero subchunks makes the chunk invisible in the 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.

    +To create an ExtPxFamily from an ExtPxAsset:

    ExtPxFamilyDesc familyDesc;
     familyDesc.pxAsset = pxAsset;
     familyDesc.group = tkGroup;
    @@ -48,7 +48,7 @@ You can subscribe to family events in order to sync graphics (or anything else)
     
    family->subscribe(listener);
     

    The listener will be notified with all physics actors added and removed.

    -And finally spawn the family in some world position (the first actor/actors will be created and event will be fired to the listener):

    +And finally spawn the family in some world position (the first actor/actors will be created and an event will be fired to the listener):

    ExtPxSpawnSettings spawnSettings = {
         &pxScene,
         defaultPxMaterial,
    @@ -57,11 +57,11 @@ And finally spawn the family in some world position (the first actor/actors will
     
     family->spawn(PxTransform(0, 0, 0), PxVec3(1, 1, 1), spawnSettings);
     

    -You can get families actor's either from listening to events or by calling getActors(). Every ExtPxActor matches 1 <-> 1 with TkActor (which matches NvBlastActor accordingly).

    +You can get a family's actors either from listening to events or by calling getActors(). Every ExtPxActor matches 1 <-> 1 with TkActor (which matches NvBlastActor accordingly).

    ExtPxActor* actor = ....; 
    -physx::PxRigidDynamic rigidDynamic = actor->getPxActor(); // 
    +physx::PxRigidDynamic rigidDynamic = actor->getPxActor(); 
     

    -An ExtPxActor remains internally unchanged through its lifetime. Use ExtPxActor getChunkIndices() and getPxActor() to update your graphics representation. Sample code:

    +An ExtPxActor remains internally unchanged throughout its lifetime. Use ExtPxActor getChunkIndices() and getPxActor() to update your graphics representation. Sample code:

    const uint32_t* chunkIndices;
     size_t chunkIndexCount;
     actor.getChunkIndices(chunkIndices, chunkIndexCount);
    @@ -74,12 +74,12 @@ actor.getChunkIndices(chunkIndices, chunkIndexCount);
         }
     }
     

    -In order to use joints set joint create function with ExtPxManager::setCreateJointFunction(...). It will be called when new TkJoint's are being created. All the joint updates and remove will be handled by manager internally.

    +In order to use joints set a joint creation function with ExtPxManager::setCreateJointFunction(...). It will be called when new TkJoints are being created. All the joint updates and removals will be handled by the manager internally.


    ExtImpactDamageManager

    -Impact Damage Manager - is a reference implementation for fast and easy impact damage support. It's built on top of ExtPxManager.

    -In order to use it create it:

    +Impact Damage Manager - is a reference implementation for fast and easy impact damage support. It is built on top of ExtPxManager.

    +In order to use it, create it as follows:

    ExtImpactDamageManager* impactManager = ExtImpactDamageManager::create(pxManager);
     

    Call its onContact method on every PxSimulationEventCallback onContact()

    @@ -100,7 +100,7 @@ Call its onContact method on every PxSimulationEventCallback onCont Call applyDamage() when you want the buffered damage to be applied:

    impactManager->applyDamage();
     

    -N.B. for impact damage to work, you must enable contact notification with custom the filter shader for PxScene. ExtImpactDamageManager has a reference filter shader implementation which can be used for that:

    +N.B. for impact damage to work, you must enable contact notification with custom filter shader for PxScene. ExtImpactDamageManager has a reference filter shader implementation which can be used for that:

    PxSceneDesc sceneDesc;
     sceneDesc.filterShader = ExtImpactDamageManager::FilterShader;
     

    @@ -117,7 +117,7 @@ And then call update() every frame:

    stressSolver->update(doDamage);

    By default it will apply scene gravity on static actors and centrifugal force on dynamic actors.

    -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:

    +The underlying ExtStressSolver can be accessed using ExtPxStressSolver::getSolver(). For example, to apply impulse to a particular actor, applyImpulse(...) can be called for additional stress to apply:

    stressSolver->getSolver().addForce(actor, position, impulse);
     

    Finally, the stress solver (and its underlying ExtStressSolver) may be released using

    @@ -126,16 +126,16 @@ Finally, the stress solver (and its underlying ExtStressSolver) may be released

    ExtSync

    -Synchronization Extension (NvBlastExtSync) - is a reference implementation for synchronizing Blast state.

    +Synchronization Extension (NvBlastExtSync) - is a reference implementation for synchronizing Blast™ state.

    The idea is that you can use it to write synchronization events to the buffer (on server for example) and then apply this buffer on a client. TkFamily ID should be properly set for that.

    3 types of events are supported:

    • ExtSyncEventType::Fracture: Fracture event. Contains fracture commands information on particular TkFamily. Applied incrementally. Relatively small.
    • ExtSyncEventType::FamilySync: Family sync event. Contains all necessary information to fully sync TkFamily state.
    • ExtSyncEventType::Physics: Physics sync event. Contains all necessary information to fully sync ExtPxFamily state.

    -In order to use it create ExtSync:

    +In order to use it, create ExtSync:

    ExtSync* sync = ExtSync::create();
     

    -Then let ExtSync insatnce listen to family fracture commands and write them to internal buffer:

    +Then let ExtSync instance listen to family fracture commands and write them to internal buffer:

    TkFamily* family = ...;
     family->addListener(*sync);
     
    diff --git a/docs/api_docs/files/pageextpxserialization.html b/docs/api_docs/files/pageextpxserialization.html
    index 92e056f..3fb2843 100644
    --- a/docs/api_docs/files/pageextpxserialization.html
    +++ b/docs/api_docs/files/pageextpxserialization.html
    @@ -22,7 +22,7 @@
     

    ExtPhysX Serialization (NvBlastExtPxSerialization)

    This extension contains serializers which can be loaded into the ExtSerialization manager defined in Serialization (NvBlastExtSerialization).

    To use this extension, you must also load the ExtSerialization extension and create a serialization manager as described in Serialization (NvBlastExtSerialization).

    -We repeat this here (again, assuming we're in the Nv::Blast namespace):

    +We repeat this here (again, assuming we are in the Nv::Blast namespace):

    ExtSerialization* ser = NvBlastExtSerializationCreate();
     

    Then, call the function NvBlastExtPxSerializerLoadSet, declared in NvBlastExtPxSerialization.h, passing in your TkFramework (required by ExtPhysX), along with your physx::PxPhysics and physx::PxCooking pointers:

    @@ -43,7 +43,9 @@ As with low-level assets, you can serialize using the serialization manager dire uint64_t size = ser->serializeIntoBuffer(buffer, asset, ExtPxObjectTypeID::Asset);

    or use the wrapper function defined in NvBlastExtPxSerialization.h:

    -/code void* buffer; uint64_t size = NvBlastExtSerializationSerializeExtPxAssetIntoBuffer(buffer, *ser, asset); /endcode

    +

    void* buffer;
    +uint64_t size = NvBlastExtSerializationSerializeExtPxAssetIntoBuffer(buffer, *ser, asset);
    +


    diff --git a/docs/api_docs/files/pageextserialization.html b/docs/api_docs/files/pageextserialization.html index 4a72cd9..3f263d0 100644 --- a/docs/api_docs/files/pageextserialization.html +++ b/docs/api_docs/files/pageextserialization.html @@ -44,10 +44,15 @@ Each serialization module defines the object types it can serialize. ExtSerializ
  • LlObjectTypeID::Asset - An NvBlastAsset
  • LlObjectTypeID::Family - An NvBlastFamily
  • To serialize an object, for example an NvBlastAsset, use ExtSerialization::serializeIntoBuffer as follows:

    -/code const NvBlastAsset* asset = ... // Given pointer to an NvBlastAsset

    -void* buffer; uint64_t size = ser->serializeIntoBuffer(buffer, asset, LlObjectTypeID::Asset); /endcode

    -If successful, the data is written into a buffer allocated using the NvBlastGlobals allocator, written to the "buffer" parameter, and the size of the buffer written is the return value of the function. If the function returns 0, then serialization was unsuccessful. Notice that the second function parameter is actually a void*, so it requires the last parameter to tell it what object it's serializing. A utility wrapper function is given in NvBlastExtLlSerialization.h which performs the same operation with an NvBlastAsset, so one could equivalently use

    -/code void* buffer; uint64_t size = NvBlastExtSerializationSerializeAssetIntoBuffer(buffer, *ser, asset); /endcode

    +

    const NvBlastAsset* asset = ... // Given pointer to an NvBlastAsset
    +
    +void* buffer;
    +uint64_t size = ser->serializeIntoBuffer(buffer, asset, LlObjectTypeID::Asset);
    +

    +If successful, the data is written into a buffer allocated using the NvBlastGlobals allocator, written to the "buffer" parameter, and the size of the buffer written is the return value of the function. If the function returns 0, then serialization was unsuccessful. Notice that the second function parameter is actually a void*, so it requires the last parameter to tell it what object it is serializing. A utility wrapper function is given in NvBlastExtLlSerialization.h which performs the same operation with an NvBlastAsset, so one could equivalently use

    +

    void* buffer;
    +uint64_t size = NvBlastExtSerializationSerializeAssetIntoBuffer(buffer, *ser, asset);
    +

    A corresponding function also exists for NvBlastFamily, as well as other data types supported by other serialization extensions.

    This buffer may be written to disk, memory, networked, etc. Since the memory for the buffer is allocated using the allocator in NvBlastGlobals, it may be freed using the same allocator:

    NVBLAST_FREE(buffer)
    @@ -117,7 +122,7 @@ If you don't know the object type in the buffer, you may use the last (optional)
     

    Peeking at and Skipping Buffer Data

    -If a buffer contains multiple objects, you may peek at the buffer to get object information including object type, encoding, and data size, and skip to the next object in the buffer (whether or not you've chosen to read the current object). For example:

    +If a buffer contains multiple objects, you may peek at the buffer to get object information including object type, encoding, and data size, and skip to the next object in the buffer (whether or not you have chosen to read the current object). For example:

    const void* buffer = ... // The input buffer
     uint64_t size = ... // The input buffer size
     
    diff --git a/docs/api_docs/files/pageextstress.html b/docs/api_docs/files/pageextstress.html
    index a082f9d..5f2c878 100644
    --- a/docs/api_docs/files/pageextstress.html
    +++ b/docs/api_docs/files/pageextstress.html
    @@ -20,34 +20,34 @@
     		
    -

    Stress Solver Extension (NvBlastExtStress)

    The Blast™ stress solver extension provides implementation of quite fast and easy to use stress solver which works directly with bond graph. It simulates more complex damage model on support graph by allowing to apply forces on nodes of support graph (on chunks). The most common usage is just applying gravity force on a static construction so that it will fall apart at some point when carcass can't hold anymore. Dynamic actors are also supported, you could for example add centrifugal force so that rotating object fast enough will break bonds.

    -It is also can be used as an another way to apply impact damage, which can give visually pleasant result of breaking actor in a weak place instead of the place of contact.

    +

    Stress Solver Extension (NvBlastExtStress)

    The Blast™ stress solver extension provides an implementation of a quite fast and easy to use stress solver which works directly with the bond graph. It simulates more complex damage model on support graph by allowing to apply forces on nodes of the support graph (on chunks). The most common usage is just applying gravity force on a static construction so that it will fall apart at some point when the carcass cannot hold anymore. Dynamic actors are also supported, you could for example add centrifugal force so that rotating an object fast enough will break bonds.

    +It also can be used as another way to apply impact damage, which can give the visually pleasant result of an actor breaking in a weak place instead of the place of contact.


    Features

      -
    • Requires only core NvBlast
    • Supports both static and dynamic actors
    • Propagates both linear and angular momentum
    • Graph complexity selection (reduces support graph to smaller size trade off speed and quality)
    • Apply stress damage on Blast Actor
    • Debug Render
    +
  • Requires only core NvBlast
  • Supports both static and dynamic actors
  • Propagates both linear and angular momentum
  • Graph complexity selection (reduces support graph to smaller size to trade-off speed for quality)
  • Apply stress damage on Blast™ actor
  • Debug Render

  • -

    +

    Settings Tuning

    -Computational time is linearly proprtional to bondIterationsPerFrame setting. To fine tune look for balance between bondIterationsPerFrame and graphReductionLevel . 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.

    -Debug render could help a lot with that, consider using stressSolver->fillDebugRender(...) for that.

    +Computational time is linearly proportional to the bondIterationsPerFrame setting. To fine tune, look for balance between bondIterationsPerFrame and graphReductionLevel . The more bond iterations are set, the more precise the computation will be. The smaller graph allows to make higher fidelity computations within the same bond iterations per frame (same time spent), but actual cracks (damaged bonds) will be more sparse as the result.

    +Debug render can help a lot for tuning, consider using stressSolver->fillDebugRender(...) for that.


    Usage

    -In order to use it create an instance with ExtStressSolver::create(...).

    +In order to use the stress solver, create an instance with ExtStressSolver::create(...).

    ExtStressSolver* stressSolver = ExtStressSolver::create(family, settings);
     

    ExtStressSolverSettings are passed in create function, but also can be changed at any time with stressSolver->setSettings(...).

    -It fully utilizes the fact that it knows initial support graph structure and does maximum of processing in create(...) method calls. After that all actors split calls are synced internally quite fast and only the actual stress propagation takes most of computational time.

    -Then you need to provide physics specific information (mass, volume, position, static) for every node in support graph since Blast itself is physics agnostic. There are two ways to do it, you can call stressSolver->setNodeInfo(...) for every graph node. Another was is to call stressSolver->setAllNodesInfoFromLL() once all the data will be populated using NvBlastAsset chunk's data, in particular volume and centroid are used. All nodes connected to 'world' chunk are marked as static.

    +It fully utilizes the fact that it knows the initial support graph structure and does a maximum of processing in the create(...) method call. After that, all actor split calls are synchronized internally and efficiently so only the actual stress propagation takes most of computational time.

    +You need to provide physics specific information (mass, volume, position, static) for every node in support graph since Blast™ itself is physics agnostic. There are two ways to do it. One way is to call stressSolver->setNodeInfo(...) for every graph node. The other way is to call stressSolver->setAllNodesInfoFromLL() once: all the data will be populated using NvBlastAsset chunk's data, in particular volume and centroid. All nodes connected to 'world' chunk are marked as static.

    stressSolver->setAllNodesInfoFromLL();
     

    -Stress solver needs to keep track for actor create/destroy events in order to update it's internal stress graph accordingly. So you need to call stressSolver->notifyActorCreated(actor) and stressSolver->notifyActorDestroyed(actor) every time actor is created or destroyed including the initial actor family had when stress solver were created. There is no need to track actors which contain only one or lesser graph nodes in that case notifyActorCreated(actor) returns 'false' as a hint, it means that stress solver will ignore them. For those actors applying forces is also doesn't make any sense.

    -Typical update loop would can look like this:

    +Stress solver needs to keep track for actor create/destroy events in order to update its internal stress graph accordingly. So you need to call stressSolver->notifyActorCreated(actor) and stressSolver->notifyActorDestroyed(actor) every time an actor is created or destroyed, including the initial actor the family had when the stress solver was created. There is no need to track actors which contain only one or less graph nodes. In that case notifyActorCreated(actor) returns 'false' as a hint. It means that the stress solver will ignore them, as for those actors applying forces does not make any sense.

    +A typical update loop looks like this:

      -
    1. If split happend call relevant stressSolver->notifyActorCreated(actor) and stressSolver->notifyActorDestroyed(actor)
    2. Apply all forces, use stressSolver->addForce(...), stressSolver->addGravityForce(...), stressSolver->addAngularVelocity(...)
    3. Call stressSolver->update(). This is where all expensive computation happens.
    4. If stressSolver->getOverstressedBondCount() > 0 use one of stressSolver->generateFractureCommands() methods to get bond fracture commands and apply on them actors.
    +
  • If split happened, call relevant stressSolver->notifyActorCreated(actor) and stressSolver->notifyActorDestroyed(actor)
  • Apply all forces, use stressSolver->addForce(...), stressSolver->addGravityForce(...), stressSolver->addAngularVelocity(...)
  • Call stressSolver->update(). This is where all expensive computation takes place.
  • If stressSolver->getOverstressedBondCount() > 0, use one of stressSolver->generateFractureCommands() methods to get bond fracture commands and apply them on actors.
  • Example code from ExtPxStressSolverImpl:

    void ExtPxStressSolverImpl::onActorCreated(ExtPxFamily& /*family*/, ExtPxActor& actor)
    @@ -100,7 +100,7 @@ Example code from ExtPxStressSolverImpl:

    } }

    -Have a look at ExtPxStressSolver implementation code, which is basically high level wrapper on NvBlastExtStress to couple it with PhysX™ and NvBlatExtPx extension (see ExtPxStressSolver).

    +Have a look at ExtPxStressSolver implementation code, which is basically a high level wrapper on NvBlastExtStress to couple it with PhysX™ and NvBlastExtPx extension (see ExtPxStressSolver).


    diff --git a/docs/api_docs/files/pageexttkserialization.html b/docs/api_docs/files/pageexttkserialization.html index ef75639..7dd6ea7 100644 --- a/docs/api_docs/files/pageexttkserialization.html +++ b/docs/api_docs/files/pageexttkserialization.html @@ -22,7 +22,7 @@

    BlastTk Serialization (NvBlastExtTkSerialization)

    This extension contains serializers which can be loaded into the ExtSerialization manager defined in Serialization (NvBlastExtSerialization).

    To use this extension, you must also load the ExtSerialization extension and create a serialization manager as described in Serialization (NvBlastExtSerialization).

    -We repeat this here (again, assuming we're in the Nv::Blast namespace):

    +We repeat this here (again, assuming we are in the Nv::Blast namespace):

    ExtSerialization* ser = NvBlastExtSerializationCreate();
     

    Then, call the function NvBlastExtTkSerializerLoadSet, declared in NvBlastExtTkSerialization.h, passing in your TkFramework:

    @@ -41,7 +41,9 @@ As with low-level assets, you can serialize using the serialization manager dire uint64_t size = ser->serializeIntoBuffer(buffer, asset, TkObjectTypeID::Asset);

    or use the wrapper function defined in NvBlastExtTkSerialization.h:

    -/code void* buffer; uint64_t size = NvBlastExtSerializationSerializeTkAssetIntoBuffer(buffer, *ser, asset); /endcode

    +

    void* buffer;
    +uint64_t size = NvBlastExtSerializationSerializeTkAssetIntoBuffer(buffer, *ser, asset);
    +


    diff --git a/docs/api_docs/files/pageglobalsapi.html b/docs/api_docs/files/pageglobalsapi.html index 0e0b8b5..34cca9a 100644 --- a/docs/api_docs/files/pageglobalsapi.html +++ b/docs/api_docs/files/pageglobalsapi.html @@ -52,7 +52,7 @@ and accessed using

    An internal, default error callback is used if the user does not set their own, or if NULL is passed into NvBlastGlobalSetErrorCallback.

    -This error callback is used by NvBlastTk, as well as many extensions. In addition, utility macros are provided such as NVBLAST_LOG_ERROR and NVBLAST_LOG_WARNDING.

    +This error callback is used by NvBlastTk, as well as many extensions. In addition, utility macros are provided such as NVBLAST_LOG_ERROR and NVBLAST_LOG_WARNING.

    Finally, a function with signature given by NvBlastLog is provided which uses the global error callback,

    diff --git a/docs/api_docs/files/pagehlapi.html b/docs/api_docs/files/pagehlapi.html index 72888e3..ef9c0b1 100644 --- a/docs/api_docs/files/pagehlapi.html +++ b/docs/api_docs/files/pagehlapi.html @@ -44,7 +44,6 @@ The high-level API, NvBlastTk (Tk stands for "toolkit"), is intended to be a mor For the remainder of this page we will be in the Nv::Blast namespace, and will drop the explicit scope Nv::Blast:: from our names.

    -BlastTk access the

    BlastTk adds:

    • An object class hierarchy (see NvBlastTk Class Hierarchy, below).
    • A global framework, TkFramework (a singleton). This keeps track of TkIdentifiable objects and allows the user to query them based upon either GUID or TkIdentifiable subclass type, and also provides a number of functions to create the various objects in BlastTk.
    • Processing groups with a task interface (see TkGroup).
    • Event dispatching for actor families (see TkFamily).
    • Intra-actor and inter-actor joint management (see TkJoint). Note, these "joints" only hold descriptor data, since physical objects are not handled by BlastTk.
    @@ -53,40 +52,40 @@ BlastTk adds:

    NvBlastTk Class Hierarchy

      -
    • There are two abstract interfaces, one of which deriving from the other: TkObject <- TkIdentifiable.
        +
      • There are two abstract interfaces, one of which deriving from the other: TkObject <- TkIdentifiable.
        • Lightweight objects are derived from TkObject.
        • Objects which use a GUID and class identification are derieved from TkIdentifiable.
        -
      • TkAsset derives from TkIdentifiable. This is mostly a wrapper for NvBlastAsset, however it also stores extra data associated with the asset such as internal joint descriptors.
      • TkFamily derives from TkIdentifiable. One of these objects is made when a TkActor is instanced from a TkAsset. All actors that are created by splitting the family's original actor remain within the same family. Actor and joint events are dispatched from the TkFamily.
      • TkGroup derives from TkIdentifiable. Groups are processing units. The user may create as many groups as they please, and add or remove actors as they please from groups. The group provides a worker (TkGroupWorker) interface which allows the user to process multiple jobs in the group asynchoronously. These jobs, along with a call to TkGroup::endProcess(), perform the tasks of generating fracture commands, applying fracture commands, and actor splitting at the low-level. The user is informed of splitting through listeners given to TkFamily objects.
      • TkActor derives from TkObject. It is mostly a wrapper for NvBlastActor, but it also provides a number of damage functions to the user.
      • TkJoint derives from TkObject. TkAsset descriptors, cause internal TkJoint obejcts to be created within an actor (joining chunks within the same actor). Alternatively, the TkFramework provides a function which allows the user to create an external joint between any two different actors. As actors split, internal joints may become external. The user gets notification whenever joints become external, or when actors joined by joints change or are deleted, through listeners attached to the associated TkFamily objects.
      +
    • TkAsset derives from TkIdentifiable. This is mostly a wrapper for NvBlastAsset, however it also stores extra data associated with the asset such as internal joint descriptors.
    • TkFamily derives from TkIdentifiable. One of these objects is made when a TkActor is instanced from a TkAsset. All actors that are created by splitting the family's original actor remain within the same family. Actor and joint events are dispatched from the TkFamily.
    • TkGroup derives from TkIdentifiable. Groups are processing units. The user may create as many groups as they please, and add or remove actors as they please from groups. The group provides a worker (TkGroupWorker) interface which allows the user to process multiple jobs in the group asynchoronously. These jobs, along with a call to TkGroup::endProcess(), perform the tasks of generating fracture commands, applying fracture commands, and actor splitting at the low-level. The user is informed of splitting through listeners given to TkFamily objects.
    • TkActor derives from TkObject. It is mostly a wrapper for NvBlastActor, but it also provides a number of damage functions to the user.
    • TkJoint derives from TkObject. TkAsset descriptors, cause internal TkJoint obejcts to be created within an actor (joining chunks within the same actor). Alternatively, the TkFramework provides a function which allows the user to create an external joint between any two different actors. As actors split, internal joints may become external. The user gets notification whenever joints become external, or when actors joined by joints change or are deleted, through listeners attached to the associated TkFamily objects.

    -
    -

    +
    +

    Linking and Header Files

    - To use the BlastTk library, the application need only inlclude the header NvBlastTk.h, found in the include/toolkit folder, and link against the appropriate version of the NvBlastTk library. Depending on the platform and configuration, various suffixes will be added to the library name. The general naming scheme is

    -NvBlastTk(config)(arch).(ext)

    -(config) is DEBUG, CHECKED, OR PROFILE for the corresponding configurations. For a release configuration there is no (config) suffix.

    -(arch) is _x86 or _x64 for Windows 32- and 64-bit builds, respectively, and empty for non-Windows platforms.

    -(ext) is .lib for static linking and .dll for dynamic linking on Windows. On XBoxOne it is .lib, and on PS4 it is .a.

    -
    -

    +To use the BlastTk library, the application need only inlclude the header NvBlastTk.h, found in the include/toolkit folder, and link against the appropriate version of the NvBlastTk library. Depending on the platform and configuration, various suffixes will be added to the library name. The general naming scheme is

    +NvBlastTk(config)(arch).(ext)

    +(config) is DEBUG, CHECKED, OR PROFILE for the corresponding configurations. For a release configuration there is no (config) suffix.

    +(arch) is _x86 or _x64 for Windows 32- and 64-bit builds, respectively, and empty for non-Windows platforms.

    +(ext) is .lib for static linking and .dll for dynamic linking on Windows. On XBoxOne it is .lib, and on PS4 it is .a.

    +
    +

    Creating the TkFramework

    - As a reminder, in this document we assume we are in the Nv::Blast namespace:

    -

    using Nv::Blast;
    -

    -In order to use NvBlastTk, one first has to create a TkFramework singleton. This simply requires a call to the global function NvBlastTkFrameworkCreate:

    -

    TkFramework* framework = NvBlastTkFrameworkCreate();
    -

    -The framework may be accessed via:

    -

    TkFramework* framework = NvBlastTkFrameworkGet();
    -

    -In the sections that follow, it is assumed that a framework has been created, and we have a pointer to it named 'framework' within scope.

    -Finally, to release the framework, use

    -

    framework->release();
    -

    -This will release all assets, families, actors, joints, and groups.

    -
    -

    +As a reminder, in this document we assume we are in the Nv::Blast namespace:

    +

    using namespace Nv::Blast;
    +

    +In order to use NvBlastTk, one first has to create a TkFramework singleton. This simply requires a call to the global function NvBlastTkFrameworkCreate:

    +

    TkFramework* framework = NvBlastTkFrameworkCreate();
    +

    +The framework may be accessed via:

    +

    TkFramework* framework = NvBlastTkFrameworkGet();
    +

    +In the sections that follow, it is assumed that a framework has been created, and we have a pointer to it named 'framework' within scope.

    +Finally, to release the framework, use

    +

    framework->release();
    +

    +This will release all assets, families, actors, joints, and groups.

    +
    +

    Creating a TkAsset

    - The TkAsset object is a high-level wrapper for the low-level NvBlastAsset (see Creating an Asset from a Descriptor (Authoring)). The descriptor used to create a TkAsset, a TkAssetDesc, is derived from NvBlastAssetDesc. The base fields should be filled in as described in (Creating an Asset from a Descriptor (Authoring)). The new field is an optional array of flags to be associated with each bond in the base descriptor. Currently the only flag is "BondJointed," and if set will cause an "internal joint" to be created in actors (TkActor type) created from the asset. See (Joints) for more on joints in BlastTk.

    -

    TkAssetDesc desc;
    +The TkAsset object is a high-level wrapper for the low-level NvBlastAsset (see Creating an Asset from a Descriptor (Authoring)). The descriptor used to create a TkAsset, a TkAssetDesc, is derived from NvBlastAssetDesc. The base fields should be filled in as described in (Creating an Asset from a Descriptor (Authoring)). The new field is an optional array of flags to be associated with each bond in the base descriptor. Currently the only flag is "BondJointed," and if set will cause an "internal joint" to be created in actors (TkActor type) created from the asset. See (Joints) for more on joints in BlastTk.

    +

    TkAssetDesc desc;
     
     myFunctionToFillInLowLevelAssetFields(desc);    // Fill in the low-level (NvBlastAssetDesc) fields as usual
     
    @@ -102,16 +101,16 @@ std::vector<uint8_t*> bondFlags(desc.bondCount, 0); 
     }
     
     TkAsset* asset = framework->createAsset(desc);  // Create a new TkAsset
    -

    -The createAsset function used above creates a low-level NvBlastAsset from the base fields of the descriptor, and then adds internal joint descriptors based upon the bonds' centroids and attached chunks. An alternative method to create a TkAsset allows the user to pass in a pre-existing NvBlastAsset, and a list of joint descriptors. If the TkAsset is to have no internal joints, then the joint descriptors are not necessary and with an NvBlastAsset pointer llAsset, a TkAsset may be created simply by using

    -

    TkAsset* asset = framework->createAsset(llAsset);
    -

    -By default, such a TkAsset will not "own" the llAsset. When the TkAsset is released, the llAsset memory will be untouched. You can pass ownership to the TkAsset using all of the default parameters of the createAsset function:

    -

    TkAsset* asset = framework->createAsset(llAsset, nullptr, 0, true);
    -

    -The last parameter sets ownership. N.B.: in order for the TkAsset to own the underlying llAsset, and therefore release it when the TkAsset is released, the memory for the llAsset must be allocated using the allocator accessed through NvBlastGlobals (see Globals API (NvBlastGlobals)).

    -If one wants to author internal joints in a TkAsset using this second createAsset method, one must pass in a valid array of joint descriptors of type TkAssetJointDesc. Each joint descriptor takes two positions and two node indices. The positions are the joint's attachment positions in asset space, and the nodes indices are those of the graph nodes that correspond to support chunks. These indices are not, in general, the same as the chunk indices. An example of initialization of the joint descriptors is given below.

    -

    std::vector<TkAssetJointDesc> jointDescs(jointCount);   // Assume jointCount = the number of joints to add
    +

    +The createAsset function used above creates a low-level NvBlastAsset from the base fields of the descriptor, and then adds internal joint descriptors based upon the bonds' centroids and attached chunks. An alternative method to create a TkAsset allows the user to pass in a pre-existing NvBlastAsset, and a list of joint descriptors. If the TkAsset is to have no internal joints, then the joint descriptors are not necessary and with an NvBlastAsset pointer llAsset, a TkAsset may be created simply by using

    +

    TkAsset* asset = framework->createAsset(llAsset);
    +

    +By default, such a TkAsset will not "own" the llAsset. When the TkAsset is released, the llAsset memory will be untouched. You can pass ownership to the TkAsset using all of the default parameters of the createAsset function:

    +

    TkAsset* asset = framework->createAsset(llAsset, nullptr, 0, true);
    +

    +The last parameter sets ownership. N.B.: in order for the TkAsset to own the underlying llAsset, and therefore release it when the TkAsset is released, the memory for the llAsset must be allocated using the allocator accessed through NvBlastGlobals (see Globals API (NvBlastGlobals)).

    +If one wants to author internal joints in a TkAsset using this second createAsset method, one must pass in a valid array of joint descriptors of type TkAssetJointDesc. Each joint descriptor takes two positions and two node indices. The positions are the joint's attachment positions in asset space, and the nodes indices are those of the graph nodes that correspond to support chunks. These indices are not, in general, the same as the chunk indices. An example of initialization of the joint descriptors is given below.

    +

    std::vector<TkAssetJointDesc> jointDescs(jointCount);   // Assume jointCount = the number of joints to add
     jointDescs[0].nodeIndices[0] = 0;   // Attach node 0 to node 1
     jointDescs[0].nodeIndices[1] = 1;
     jointDescs[0].attachPoistions[0] = physx::PxVec3( 1.0f, 2.0f, 3.0f );   // Attachment positions are often the same within an asset, but they don't have to be
    @@ -119,42 +118,43 @@ jointDescs[0].attachPoistions[1] = physx::PxVec3( 1.0f, 2.0f, 3.0f );
     // ... etc.
     
     TkAsset* asset = framework->createAsset(llAsset, jointDescs.data(), jointDescs.size());
    -

    -The code above assumes you know the support graph nodes to which you'd like to attach joints. Often, the user only knows the corresponding chunk indices. Fortunately it's easy to map chunk indices to graph node indices. In order to get the map, use the low-level function

    -

    const uint32_t map = NvBlastAssetGetChunkToGraphNodeMap(llAsset, logFn);
    -

    -This map is an array with an entry for every chunk index. To get the graph node index for a chunk indexed chunkIndex, use

    -

    uint32_t nodeIndex = map[chunkIndex];
    -

    -If the chunk indexed by chunkIndex does not correspond to a support chunk, then the mapped value will be UINT32_MAX, the invalid index. Otherwise, the mapped value will be a valid graph node index.

    -Finally, to release a TkAsset, as with any TkObject-derived object, use the release() method:

    -asset->release();

    -
    -

    +

    +The code above assumes you know the support graph nodes to which you'd like to attach joints. Often, the user only knows the corresponding chunk indices. Fortunately it's easy to map chunk indices to graph node indices. In order to get the map, use the low-level function

    +

    +This map is an array with an entry for every chunk index. To get the graph node index for a chunk indexed chunkIndex, use

    +

    uint32_t nodeIndex = map[chunkIndex];
    +

    +If the chunk indexed by chunkIndex does not correspond to a support chunk, then the mapped value will be UINT32_MAX, the invalid index. Otherwise, the mapped value will be a valid graph node index.

    +Finally, to release a TkAsset, as with any TkObject-derived object, use the release() method:

    +

    asset->release();
    +

    +
    +

    Instancing a TkAsset: Creation of a TkActor and a TkFamily

    - Whereas with the Blast™ low-level (Low Level API (NvBlast)), one must explicitly create a family (NvBlastFamily) from an asset (NvBlastAsset) before creating the first actor (NvBlastActor) in the family, NvBlastTk creates a TkFamily automatically when an unfractured TkActor is instanced from a TkAsset using the framework's createActor function. This family is accessible through the actor and any actor that is created from splitting it. The family is not released automatically when all actors within it have been released. The user must use the TkFamily's release() method (see TkObject base API) to do so. (Or wait until the framework is released.) If a family is released that contains actors, the actors within will be released as well.

    -The TkFamily has a special roll in NvBlastTk, holding user-supplied event listeners (TkEventListener). All internal actor creation and destruction events are broadcast to listeners through split events (TkSplitEvent). These signal when a fracturing operation has destroyed an actor and created child actors from it. TkActor creation or release that occurs from an explicit API call do not produce events. For example when creating a first unfractured instance of an asset using createAsset, or when calling the release() method on a TkActor. TkJoint events are similarly broadcast to receivers (TkJointEvent). These signal when the actors which are joined by the joints change, so that the user may update a corresponding physical joint. They also signal when a joint no longer attaches actors and is therefore unreferenced. The user may invalidate or release the joint using the TkObject release() method when this occurs (more on joint ownership in Joints).

    -To create an unfractured TkActor instance from a TkAsset, one first fills in a descriptor (TkActorDesc) and passes it to the framework's createActor function. As with the TkAssetDesc, the TkActorDesc is derived from its low-level counterpart, the NvBlastActorDesc. In addition the TkActorDesc holds a pointer to the TkAsset being instanced. An example of TkActor creation is given below, given a TkAsset pointer asset.

    -

    TkActorDesc desc;   // The TkActorDesc constructor sets sane default values for the base (NvBlastActorDesc) fields, giving uniform chunk and bond healths of 1.0.
    +Whereas with the Blast™ low-level (Low Level API (NvBlast)), one must explicitly create a family (NvBlastFamily) from an asset (NvBlastAsset) before creating the first actor (NvBlastActor) in the family, NvBlastTk creates a TkFamily automatically when an unfractured TkActor is instanced from a TkAsset using the framework's createActor function. This family is accessible through the actor and any actor that is created from splitting it. The family is not released automatically when all actors within it have been released. The user must use the TkFamily's release() method (see TkObject base API) to do so. (Or wait until the framework is released.) If a family is released that contains actors, the actors within will be released as well.

    +The TkFamily has a special role in NvBlastTk, holding user-supplied event listeners (TkEventListener). All internal actor creation and destruction events are broadcast to listeners through split events (TkSplitEvent). These signal when a fracturing operation has destroyed an actor and created child actors from it. TkActor creation or release that occurs from an explicit API call do not produce events. For example when creating a first unfractured instance of an asset using createAsset, or when calling the release() method on a TkActor. TkJoint events are similarly broadcast to receivers (TkJointEvent). These signal when the actors which are joined by the joints change, so that the user may update a corresponding physical joint. They also signal when a joint no longer attaches actors and is therefore unreferenced. The user may invalidate or release the joint using the TkObject release() method when this occurs (more on joint ownership in Joints).

    +To create an unfractured TkActor instance from a TkAsset, one first fills in a descriptor (TkActorDesc) and passes it to the framework's createActor function. As with the TkAssetDesc, the TkActorDesc is derived from its low-level counterpart, the NvBlastActorDesc. In addition the TkActorDesc holds a pointer to the TkAsset being instanced. An example of TkActor creation is given below, given a TkAsset pointer asset.

    +

    TkActorDesc desc;   // The TkActorDesc constructor sets sane default values for the base (NvBlastActorDesc) fields, giving uniform chunk and bond healths of 1.0.
     desc.asset = asset; // This field of TkActorDesc must be set to a valid asset pointer.
     
     TkActor* actor = framework->createActor(desc);
    -

    -The TkFamily created with the actor above may be accessed through the actor's getFamily field:

    -

    TkFamily& family = actor->getFamily();
    -

    -The returned value is a reference since a TkActor's family can never be NULL. Actors resulting from the split of a "parent" actor will always belong to the parent's family.

    -For most applications, the user will need to create a listener object to pass to every family created, in order to keep their physics and graphics representations in sync with the splitting of the TkActor. For more on this, see Events.

    -
    -

    +

    +The TkFamily created with the actor above may be accessed through the actor's getFamily field:

    +

    +The returned value is a reference since a TkActor's family can never be NULL. Actors resulting from the split of a "parent" actor will always belong to the parent's family.

    +For most applications, the user will need to create a listener object to pass to every family created, in order to keep their physics and graphics representations in sync with the splitting of the TkActor. For more on this, see Events.

    +
    +

    Groups

    - One important feature of NvBlastTk is the ability to multitask damage processing. The mechanism by which the toolkit does this is the group object, TkGroup. Groups are created at the request of the user; the user may create as many groups as he or she likes. Actors may be added or removed from groups in any way the user wishes, with the only constraint being that a given actor may belong to no more than one group. A group is a processing object, much like a scene in a physics simulation. Indeed, a natural pattern would be to associate one group per physics scene, and synchronize the group processing with scene simulation. Another pattern would be to subdivide the world into neighborhoods, and associate each neighborhood with a group. A distributed game could take advantage of this structure to similarly distribute computation.

    -Group processing is performed by workers, which have a TkGroupWorker API exposed to the user. The number of workers may be set by the user, with the idea being that this should correspond to the number of threads available for group processing. Processing starts with a call to TkGroup::startProcess(). This creates a number of jobs which the user may assign to workers as they like, each worker potentially on its own thread. The jobs calculate the effects of all damage taken by the group's actors. After all jobs have been run, the user must call TkGroup::endProcess(). This will result in all events being fired off to listeners associated with families with actors in the group.

    -A convenience function, TkGroup::process(), is provided which uses one worker to perform all jobs sequentially on the calling thread. This is useful shortcut to get BlastTk up and running quickly. A multithreaded group processing implementation is given by Nv::Blast::ExtGroupTaskManagerImpl (in NvBlastExtPxTaskImpl.h). This resides in PhysX Extensions (NvBlastExtPhysX), because it uses physx::PxTask.

    -Actors resulting from the split of a "parent" actor will be placed automatically into the group that the parent belonged to. This is similar to the assigment of families from a split, except that unlike families, the user then has the option to move the new actors to other groups, or no group at all.

    -Also similar to families, groups are not automatically released when the last actor is removed from it. Unlike families, when a group is released, the actors which belong to the group are not released. They will, however, be removed from the group before the release is complete.

    -A typical usage is outlined below. See Applying Damage to Actors and Families for methods of applying damage to actors.

    -

    // Create actors from descriptors desc1, desc2, ... etc., and attach a listener to each new family created
    +One important feature of NvBlastTk is the ability to multitask damage processing. The mechanism by which the toolkit does this is the group object, TkGroup. Groups are created at the request of the user; the user may create as many groups as he or she likes. Actors may be added or removed from groups in any way the user wishes, with the only constraint being that a given actor may belong to no more than one group. A group is a processing object, much like a scene in a physics simulation. Indeed, a natural pattern would be to associate one group per physics scene, and synchronize the group processing with scene simulation. Another pattern would be to subdivide the world into neighborhoods, and associate each neighborhood with a group. A distributed game could take advantage of this structure to similarly distribute computation.

    +Group processing is performed by workers, which have a TkGroupWorker API exposed to the user. The number of workers may be set by the user, with the idea being that this should correspond to the number of threads available for group processing. Processing starts with a call to TkGroup::startProcess(). This creates a number of jobs which the user may assign to workers as they like, each worker potentially on its own thread. The jobs calculate the effects of all damage taken by the group's actors. After all jobs have been run, the user must call TkGroup::endProcess(). This will result in all events being fired off to listeners associated with families with actors in the group.

    +A convenience function, TkGroup::process(), is provided which uses one worker to perform all jobs sequentially on the calling thread. This is useful shortcut to get BlastTk up and running quickly. A multithreaded group processing implementation is given by Nv::Blast::ExtGroupTaskManagerImpl (in NvBlastExtPxTaskImpl.h). This resides in PhysX™ Extensions (NvBlastExtPhysX), because it uses physx::PxTask.

    +Actors resulting from the split of a "parent" actor will be placed automatically into the group that the parent belonged to. This is similar to the assigment of families from a split, except that unlike families, the user then has the option to move the new actors to other groups, or no group at all.

    +Also similar to families, groups are not automatically released when the last actor is removed from it. Unlike families, when a group is released, the actors which belong to the group are not released. They will, however, be removed from the group before the release is complete.

    +A typical usage is outlined below. See Applying Damage to Actors and Families for methods of applying damage to actors.

    +

    // Create actors from descriptors desc1, desc2, ... etc., and attach a listener to each new family created
     TkActor* actor1 = framework->createActor(desc1);
     actor1->getFamily().addListener(gMyReceiver);       // gMyReceiver is a TkEventListener-derived object.  More on events in a subsequent section.
     TkActor* actor2 = framework->createActor(desc2);
    @@ -165,7 +165,7 @@ actor3->getFamily().addListener(gMyReceiver);
     
     // Let's create two groups.  First, create a group descriptor.  This may be used to create both groups.
     TkGroupDesc groupDesc;
    -groupDesc.pxTaskManager = &gTaskManager;    // physx::PxTaskManager-derived object
    +groupDesc.workerCount = 1;  // this example processes groups on the calling thread only
     
     // Now create the groups
     TkGroup* group1 = framework->createGroup(groupDesc);
    @@ -191,18 +191,18 @@ group2->process();
     // When the groups are no longer needed, they may be released with the usual release method.
     group1->release();
     group2->release();
    -

    -
    -

    +

    +
    +

    Applying Damage to Actors and Families

    - Damage in NvBlastTk uses the same damage program scheme as the low-level SDK (see Damage and Fracturing). One passes the program (NvBlastDamageProgram), damage descriptor (program-dependent), and material (also program-dependent) to a TkActor::damage function. Ultimately, the damage descriptor and material data are all parameters used by the damage program. The distinction is that the damage descriptor should describe properties of the thing doing the damage, while the material should describe properties of the actor (the thing being damaged). The interpretation of this data is entirely up to the program's functions, however.

    -For convenience, the user may set a default material in the actor's family. This assumes, of course, that the material parameters for this default are compatible with the program being used to damage the family's actors.

    -Examples of the three TkActor damage methods are given below.

    -
    -

    +Damage in NvBlastTk uses the same damage program scheme as the low-level SDK (see Damage and Fracturing). One passes the program (NvBlastDamageProgram), damage descriptor (program-dependent), and material (also program-dependent) to a TkActor::damage function. Ultimately, the damage descriptor and material data are all parameters used by the damage program. The distinction is that the damage descriptor should describe properties of the thing doing the damage, while the material should describe properties of the actor (the thing being damaged). The interpretation of this data is entirely up to the program's functions, however.

    +For convenience, the user may set a default material in the actor's family. This assumes, of course, that the material parameters for this default are compatible with the program being used to damage the family's actors.

    +Examples of the three TkActor damage methods are given below.

    +
    +

    Multiple Damage Descriptors using NvBlastProgramParams

    - N.B. - with this method of damage, the lifetime of the NvBlastProgramParams must extend at least until the TkGroup::sync call for the actor.

    -

    NvBlastDamageProgram program =
    +N.B. - with this method of damage, the lifetime of the NvBlastProgramParams must extend at least until the TkGroup::endProcess call for the actor.

    +

    NvBlastDamageProgram program =
     {
         myGraphShaderFunction,      // A function with the NvBlastGraphShaderFunction signature
         mySubgraphShaderFunction    // A function with the NvBlastSubgraphShaderFunction signature
    @@ -236,14 +236,14 @@ material.maxDamageThreshold = 0.8f;
     NvBlastProgramParams params = { damageDescs, 2, &material };
     
     // Apply damage
    -actor->damage(program, &params);    // params must be kept around until TkGroup::sync is called!
    -

    -
    -

    +actor->damage(program, &params); // params must be kept around until TkGroup::endProcess is called! +

    +
    +

    Single Damage Descriptor with Default TkFamily Material

    - This method of damage copies the damage descriptor into a buffer, so the user need not hold onto a copy after the damage function call. Only one damage descriptor may be passed in at once.

    -To use this method, the user must first set a default material in the actor's family. For example:

    -

    // The example material "Material" is modeled after NvBlastExtMaterial in the NvBlastExtShaders extension
    +This method of damage copies the damage descriptor into a buffer, so the user need not hold onto a copy after the damage function call. Only one damage descriptor may be passed in at once.

    +To use this method, the user must first set a default material in the actor's family. For example:

    +

    // The example material "Material" is modeled after NvBlastExtMaterial in the NvBlastExtShaders extension
     Material material;
     
     material.health = 10.0f;
    @@ -252,10 +252,10 @@ material.maxDamageThreshold = 0.8f;
     
     // Set the default material used by the material-less TkActor::damage call
     actor->getFamily().setMaterial(&material);
    -

    -N.B. the lifetime of the material set must extend at least until the TkGroup::sync call for the actor.

    -Then to apply damage, use:

    -

    +N.B. the lifetime of the material set must extend at least until the TkGroup::endProcess call for the actor.

    +Then to apply damage, use:

    +

    NvBlastDamageProgram program =
     {
         myGraphShaderFunction,      // A function with the NvBlastGraphShaderFunction signature
         mySubgraphShaderFunction    // A function with the NvBlastSubgraphShaderFunction signature
    @@ -273,28 +273,28 @@ damageDesc.maxRadius = 1.0f;
     
     // Apply damage
     actor->damage(program, &damageDesc, (uint32_t)sizeof(RadialDamageDesc));
    -

    -
    -

    +

    +
    +

    Single Damage Descriptor with Specified Material

    - This method is just like the one above, except that the user has the opportunity to override the material used during damage.

    -N.B. - the lifetime of the material passed in must extend at least until the TkGroup::sync call for the actor.

    -This call is just like the one above with an extra material parameter:

    -

    actor->damage(program, &damageDesc, (uint32_t)sizeof(RadialDamageDesc), &material);
    -

    -
    -

    +This method is just like the one above, except that the user has the opportunity to override the material used during damage.

    +N.B. - the lifetime of the material passed in must extend at least until the TkGroup::endProcess call for the actor.

    +This call is just like the one above with an extra material parameter:

    +

    actor->damage(program, &damageDesc, (uint32_t)sizeof(RadialDamageDesc), &material);
    +

    +
    +

    Joints

    - Joints in NvBlastTk are abstract representations of physical joints. When joints become active, change the actors they join, or become unreferenced (the actors they join disappear), the user will receive notification via a TkJointUpdateEvent (see Events).

    -Joints may be defined as a part of a TkAsset, in which case they are consisdered "internal" joints. (See Creating a TkAsset.) Since the first instance of a TkAsset is a single TkActor, internal joints are defined between chunks within the same actor. Therefore they are not active (there is no point in joining two locations in a single rigid body). Upon splitting into multiple actors, however, an internal joint's chunks may now belong to two different TkActors. When this happens, the user will receive a TkJointUpdateEvent of subtype TkJointUpdateEvent::External. The event contains a pointer to the TkJoint, and from that the user has access to the information needed to create a physical joint between the rigid bodies that correspond to the joined TkActors.

    -Joints may also be created externally at runtime, using the TkFramework::createJoint function. A joint created this way must be between two different TkActors. Because of this, the joint is immediately considered active, and so no TkJointUpdateEvent is generated from its creation. The user should create a physical joint to correspond to the joint returned by createJoint. An externally created joint of this type has another distinguishing characteristic: it may join an actor to "the world," or "Newtonial Reference Frame" (NRF). To do this, one TkFamily pointer in the joint descriptor is set to NULL. Examples are given below.

    -

    TkJointDesc desc;
    +Joints in NvBlastTk are abstract representations of physical joints. When joints become active, change the actors they join, or become unreferenced (the actors they join disappear), the user will receive notification via a TkJointUpdateEvent (see Events).

    +Joints may be defined as a part of a TkAsset, in which case they are consisdered "internal" joints. (See Creating a TkAsset.) Since the first instance of a TkAsset is a single TkActor, internal joints are defined between chunks within the same actor. Therefore they are not active (there is no point in joining two locations in a single rigid body). Upon splitting into multiple actors, however, an internal joint's chunks may now belong to two different TkActors. When this happens, the user will receive a TkJointUpdateEvent of subtype TkJointUpdateEvent::External. The event contains a pointer to the TkJoint, and from that the user has access to the information needed to create a physical joint between the rigid bodies that correspond to the joined TkActors.

    +Joints may also be created externally at runtime, using the TkFramework::createJoint function. A joint created this way must be between two different TkActors. Because of this, the joint is immediately considered active, and so no TkJointUpdateEvent is generated from its creation. The user should create a physical joint to correspond to the joint returned by createJoint. An externally created joint of this type has another distinguishing characteristic: it may join an actor to "the world," or "Newtonial Reference Frame" (NRF). To do this, one TkFamily pointer in the joint descriptor is set to NULL. Examples are given below.

    +

    TkJointDesc desc;
     desc.families[0] = &actor0->getFamily();    // Assume we have a valid actor0 pointer
     desc.chunkIndices[0] = 1;   // This chunk *must* be a support chunk in the asset that created desc.families[0]
    -desc.attachPositions[0] = physx::PxVec3(1.f, 2.f; 3.f); // The attach position is in asset space
    +desc.attachPositions[0] = physx::PxVec3(1.0f, 2.0f; 3.0f);  // The attach position is in asset space
     desc.families[1] = &actor1->getFamily();    // Assume we have a valid actor1 pointer... note, actor0 and actor1 could have the same family
     desc.chunkIndices[1] = 10;  // This chunk *must* be a support chunk in the asset that created desc.families[1]
    -desc.attachPositions[1] = physx::PxVec3(4.f, 5.f; 6.f); // The attach position is in asset space
    +desc.attachPositions[1] = physx::PxVec3(4.0f, 5.0f; 6.0f);  // The attach position is in asset space
     
     // Create the external joint from the descriptor, which joins actor0 and actor1
     TkJoint* joint = framework->createJoint(desc);
    @@ -302,30 +302,30 @@ TkJoint* joint = framework->createJoint(desc);
     // Now join actor0 to the NRF
     // desc.families[0] already contains actor0's family
     desc.chunkIndices[0] = 2;   // Again, this chunk must be a support chunk in the asset that created desc.families[0]
    -desc.attachPositions[0] = physx::PxVec3(0.f, 0.f; 0.f); // The attach position is in asset space
    +desc.attachPositions[0] = physx::PxVec3(0.0f, 0.0f; 0.0f);  // The attach position is in asset space
     desc.families[1] = nullptr; // Setting the family to NULL designates the world (NRF)
     // The value of desc.chunkIndices[1] is not used, since desc.families[1] is NULL
    -desc.attachPositions[1] = physx::PxVec3(0.f, 0.f, 10.0f);   // Attach position in the world
    +desc.attachPositions[1] = physx::PxVec3(0.0f, 0.0f, 10.0f); // Attach position in the world
     
     // Create the external joint which joins actor0 to the world
     TkJoint* jointNRF = framework->createJoint(desc);
    -

    -
    -

    +

    +
    +

    Releasing Joints

    - TkJoints are not released by Blast™, except when the TkFramework is released. Otherwise, the user is responsible for releasing TkJoints after they become unreferenced. This is facilitated by the Unreferenced subtype of the TkJointUpdateEvent. After receiving this event for joint, the user may choose to release, using the typical TkObject::release() method.

    -

    joint->release();
    -

    -Note, this method can be called at any time, even before the joint is unreferenced. When called, it will remove its references to its attached actors first, causing the joint to then become unreferenced. For example, if the user wishes to break a physical joint in their simulation, they can then release the corresponding TkJoint.

    -It should be mentioned, however, that joints created with an asset are allocated differently from external joints created using TkFramework::createJoint. Internal joints created from the joint descriptors in a TkAsset are block allocated with every TkFamily that instances the asset. Calling the release() method on those joints will remove any remaining references to them (as mentioned above), but will not perform any deallocation. Only when the TkFamily itself is released will the internal joint memory for that family be released. This is true even if the internal joints become "external" from actor splitting. Joints that become external are still associated with a single family and their memory still resides with that family.

    -On the other hand, joints that start out life external by way of the TkFramework::createJoint function have a separate allocation, and do not have memory tied to any TkFamily (even if both actors joined are in the same family). Releasing a family holding one of the actors in such a "purely external" joint will trigger a TkJointUpdateEvent of subtype Unreferenced, however, signalling that the joint is ready for user release.

    -
    -

    +TkJoints are not released by Blast™, except when the TkFramework is released. Otherwise, the user is responsible for releasing TkJoints after they become unreferenced. This is facilitated by the Unreferenced subtype of the TkJointUpdateEvent. After receiving this event for joint, the user may choose to release, using the typical TkObject::release() method.

    +

    joint->release();
    +

    +Note, this method can be called at any time, even before the joint is unreferenced. When called, it will remove its references to its attached actors first, causing the joint to then become unreferenced. For example, if the user wishes to break a physical joint in their simulation, they can then release the corresponding TkJoint.

    +It should be mentioned, however, that joints created with an asset are allocated differently from external joints created using TkFramework::createJoint. Internal joints created from the joint descriptors in a TkAsset are block allocated with every TkFamily that instances the asset. Calling the release() method on those joints will remove any remaining references to them (as mentioned above), but will not perform any deallocation. Only when the TkFamily itself is released will the internal joint memory for that family be released. This is true even if the internal joints become "external" from actor splitting. Joints that become external are still associated with a single family and their memory still resides with that family.

    +On the other hand, joints that start out life external by way of the TkFramework::createJoint function have a separate allocation, and do not have memory tied to any TkFamily (even if both actors joined are in the same family). Releasing a family holding one of the actors in such a "purely external" joint will trigger a TkJointUpdateEvent of subtype Unreferenced, however, signalling that the joint is ready for user release.

    +
    +

    Events

    - NvBlastTk uses events to communicate the results of actor splitting, joint updates from actor splitting, and fracture event buffers that can be used to synchronize fracturing between multiple clients.

    -Events are broadcast to listeners which implement the TkEventListener interface. Listeners are held by TkFamily objects. During a TkGroup::sync call (see Groups), relevant events are broadcast to the listeners in the families associated with the actors in the group.

    -A typical user's receiver implementation might take on the form shown below.

    -

    class MyActorAndJointListener : public TkEventListener
    +NvBlastTk uses events to communicate the results of actor splitting, joint updates from actor splitting, and fracture event buffers that can be used to synchronize fracturing between multiple clients.

    +Events are broadcast to listeners which implement the TkEventListener interface. Listeners are held by TkFamily objects. During a TkGroup::endProcess call (see Groups), relevant events are broadcast to the listeners in the families associated with the actors in the group.

    +A typical user's receiver implementation might take on the form shown below.

    +

    class MyActorAndJointListener : public TkEventListener
     {
         // TkEventListener interface
         void receive(const TkEvent* events, uint32_t eventCount) override
    @@ -383,31 +383,31 @@ Events

    } } }; -

    -Whenever a new TkActor is created by the user (via TkFramework::createActor, see Instancing a TkAsset: Creation of a TkActor and a TkFamily), its newly-made family should be given whatever listeners the user wishes to attach. For example,

    -

    TkActor* actor = framework->createActor(actorDesc);
    +

    +Whenever a new TkActor is created by the user (via TkFramework::createActor, see Instancing a TkAsset: Creation of a TkActor and a TkFamily), its newly-made family should be given whatever listeners the user wishes to attach. For example,

    +

    TkActor* actor = framework->createActor(actorDesc);
     
     actor->getFamily().addListener(myListener); //  myListener is an object which implements TkEventListener (see MyActorAndJointListener above, for example)
    -

    -Listeners may also be removed from families at any time.

    -
    -

    +

    +Listeners may also be removed from families at any time.

    +
    +

    Object and Type Identification

    - NvBlastTk objects that are derived from TkIdentifiable (TkAsset, TkFamily, and TkGroup) support an object and class (type) identification system. The TkIdentifiable interfaces setID and getID allow the user to set and access an NvBlastID for each object. The NvBlastID is a 128-bit identifier. TkIdentifiable objects are tracked by the TkFramework, which may be used to look up an object by its NvBlastID.

    -Upon creation, TkIdentifiable objects are given a GUID, a unique NvBlastID. The is welcome to change the object's guid at any time, with the restriction that the GUID cannot be all zero bytes.

    -With an object's GUID, one may look up the object using the TkFramework function findObjectByID:

    -

    TkIdentifiable* object = framework->findObjectByID(id); // id = an NvBlastID GUID
    -

    -If the object is found, a non-NULL pointer will be returned.

    -TkIdentifiable-derived classes also have a class identification system, the TkType interface. From an individual object one may use the TkIdentifiable interface getType to access the class's TkType interface. Alternatively, one may use the TkFramework getType function with TkTypeIndex::Enum argument. For example, to get the TkType interface for the TkAsset class, use

    -

    const TkType* assetType = framework->getType(TkTypeIndex::Asset);
    -

    -The type interface may be used:

    -

      +NvBlastTk objects that are derived from TkIdentifiable (TkAsset, TkFamily, and TkGroup) support an object and class (type) identification system. The TkIdentifiable interfaces setID and getID allow the user to set and access an NvBlastID for each object. The NvBlastID is a 128-bit identifier. TkIdentifiable objects are tracked by the TkFramework, which may be used to look up an object by its NvBlastID.

      +Upon creation, TkIdentifiable objects are given a GUID, a unique NvBlastID. The user is welcome to change the object's guid at any time, with the restriction that the GUID cannot be all zero bytes.

      +With an object's GUID, one may look up the object using the TkFramework function findObjectByID:

      +

      TkIdentifiable* object = framework->findObjectByID(id); // id = an NvBlastID GUID
      +

      +If the object is found, a non-NULL pointer will be returned.

      +TkIdentifiable-derived classes also have a class identification system, the TkType interface. From an individual object one may use the TkIdentifiable interface getType to access the class's TkType interface. Alternatively, one may use the TkFramework getType function with TkTypeIndex::Enum argument. For example, to get the TkType interface for the TkAsset class, use

      +

      const TkType* assetType = framework->getType(TkTypeIndex::Asset);
      +

      +The type interface may be used:

      +

      • to access class-specific object lists in the framework,
      • identify the class of a TkIdentifiable obtained through ID lookup or deserialization, or
      • to obtain the class's name and format version number.
      -

      -For example, to access a list of all families:

      -

      // Get the TkFamily type interface
      +

      +For example, to access a list of all families:

      +

      // Get the TkFamily type interface
       const TkType* familyType = framework->getType(TkTypeIndex::Family);
       
       // Get the family count to allocate a buffer
      @@ -416,9 +416,9 @@ std::vector<TkIdentifiable*> families(familyCount);
       
       // Write the families to the buffer
       const uint32_t familiesFound = framework->getObjects(families.data(), familyCount, familyType);
      -

      -In the above code, the values of familyCount and familiesFound should be equal. An alternative usage of TkFramework::getObjects allows the user to write to a (potentially) smaller buffer, iteratively. For example:

      -

      uint32_t familiesFound;
      +

      +In the above code, the values of familyCount and familiesFound should be equal. An alternative usage of TkFramework::getObjects allows the user to write to a (potentially) smaller buffer, iteratively. For example:

      +

      uint32_t familiesFound;
       uint32_t totalFamilyCount = 0;
       do
       {
      @@ -430,9 +430,9 @@ uint32_t totalFamilyCount = 0;
           // Process the families found so far
           myProcessFamiliesFunction(familyBuffer, familiesFound);
       } while (familiesFound == 16);
      -

      -To use the type interface to identify a class, perhaps after serialization or lookup by ID, one may do something like:

      -

      \\ Assume we have a TkIdentifiable pointer called "object"
      +

      +To use the type interface to identify a class, perhaps after serialization or lookup by ID, one may do something like:

      +

      \\ Assume we have a TkIdentifiable pointer called "object"
       
       // Get the type interfaces of interest
       const TkType* assetType = framework->getType(TkTypeIndex::Asset);
      @@ -451,11 +451,11 @@ uint32_t totalFamilyCount = 0;
       
           // Process the object as a TkFamily
       }
      -

      -A TkIdentifiable-derived class may be queried for its name using the TkType interface, using TkType::getName(). This function returns a const char pointer to a string.

      -Finally, one may query the class for its current format version number using TkType::getVersion().

      -
      -

      +

      +A TkIdentifiable-derived class may be queried for its name using the TkType interface, using TkType::getName(). This function returns a const char pointer to a string.

      +Finally, one may query the class for its current format version number using TkType::getVersion().

      +
      +

    -A bond is not created if area of interface is zero. The interface centroid is computed as center of mass of all interface polygon points. The interface normal is computed as an average of normals of all planes comprising the interface surface.

    +A bond is not created if the area of interface is zero. The interface centroid is computed as center of mass of all interface polygon points. The interface normal is computed as an average of normals of all planes comprising the interface surface.

    Note - for Blast™ to operate with satisfactory fracturing behavior, it does not require exact area, centroid, and normal values for Bonds.

    -Along with creating a Blast™ asset, ApexImporter creates an *.obj or *.fbx file with description of chunks render geometry. Blast asset data can be saved to *.llasset, *.tkasset or *.bpxa format. BPXA asset contains collision geometry and can be used in SampleAssetViewer.

    +Along with creating a Blast™ asset, ApexImporter creates an *.obj or *.fbx file with description of chunk render geometry. Blast™ asset data can be saved to *.llasset, *.tkasset or *.bpxa format. BPXA asset contains collision geometry and can be used in SampleAssetViewer.

     USAGE:
     
    diff --git a/docs/api_docs/files/pageintroduction.html b/docs/api_docs/files/pageintroduction.html
    index 9016338..e38a444 100644
    --- a/docs/api_docs/files/pageintroduction.html
    +++ b/docs/api_docs/files/pageintroduction.html
    @@ -28,7 +28,7 @@ The static data associated with a destructible is stored in an asset. A
     Chunks are defined hierarchically, so that when a chunk is fractured its child chunks are created. The user may tag any chunk in this hierarchy as a support chunk. This is covered in more detail in the Support Model section. The user also supplies a description of the connections between support chunks. A bond represents the surface joining neighboring chunks. A bond is represented by a surface centroid, an average surface normal, and the surface area. These quantities don't need to be exact for Blast™ to operate effectively.

    Multiple chunk hierarchies may exist in a single asset. The root chunks (see Definitions) will be visible when the asset is initially instanced. Subsequent fracturing has the effect of breaking the root chunks into their hierarchical descendants.

    Support Model

    -Blast™ requires that support chunks form an exact cover (see the definition of exact coverage in Definitions). The geometric interpretation of exact coverage is that the support chunks fill the space of the root (unfractured) chunk, without any volume being covered by more than one chunk. A helper function are provided to modify a set of chunk descriptors so that they have exact coverage. This function fills in missing coverage by assigning support to chunks at the highest place possible (closest to root) in the hierarchy, and redundant support is removed: if a chunk and one of its descendant chunks are both marked as support, the function will remove support from the descendant chunk.

    +Blast™ requires that support chunks form an exact cover (see the definition of exact coverage in Definitions). The geometric interpretation of exact coverage is that the support chunks fill the space of the root (unfractured) chunk, without any volume being covered by more than one chunk. A helper function is provided to modify a set of chunk descriptors so that they have exact coverage. This function fills in missing coverage by assigning support to chunks at the highest place possible (closest to root) in the hierarchy, and redundant support is removed: if a chunk and one of its descendant chunks are both marked as support, the function will remove support from the descendant chunk.

    Support chunks that are joined by bonds will be grouped together in the same actor when fracturing occurs. Bonds may be defined between any two support chunks, or between a support chunk and "the world." There is no corresponding "world chunk," but the bond represents a connection between the chunk and its external environment. All chunks with a support graph connected to the world will be put into the same actor. An expected use case is to make this actor static (or kinematic). Actors may be queried to determine if they are "world-bound."

    In order to take advantage of the chunk hieararchy to reduce the number of chunks which represent an actor physically and graphically, Blast™ calculates a list of visible chunks from the support chunks in an actor. These may be the support chunks, or they may be ancestors of support chunks if all descendant support chunks are in the actor.

    Support chunks do not have to be leaves in the chunk hierarchy, nor do they have to be at the same depth in the hierarchy. Children of support chunks will always be the sole chunk in their actor, since there are no bonds defined between them. If an actor consists of a subsupport chunk (see Definitions), the visible chunk is the same chunk. The same is true if an actor consists of a single support chunk.

    diff --git a/docs/api_docs/files/pagellapi.html b/docs/api_docs/files/pagellapi.html index 3b3c19d..f7d65a6 100644 --- a/docs/api_docs/files/pagellapi.html +++ b/docs/api_docs/files/pagellapi.html @@ -31,42 +31,42 @@ Introduction

    The low-level API is the core of Blast™ destruction. It is designed to be a minimal API that allows an experienced user to incorporate destruction into their application. Summarizing what the low-level API has, and doesn't have:

      -
    • There is no physics representation. The low-level API is agnostic with respect to any physics engine, and furthermore does not have any notion of collision geometry. The NvBlastActor is an abstraction which is intended to correspond to a rigid body. However it is up to the user to implement that connection. The NvBlastActor references a list of visible chunk indices, which correspond to NvBlastChunk data in the asset. The NvBlastChunk contains a userData field which can be used to associate collision geometry with the actor based upon the visible chunks. The same is true for constraints created between actors. Bonds contain a userData field that can be used to inform the user that actors should have joints created at a particular location, but it is up to the user to create and manage physical joints between two actors.
    • There is no graphics representation. Just as there is no notion of collision geometry, there is also no notion of graphics geometry. The NvBlastChunk userData field (see the item above) can be used to associate graphics geometry with the actor based upon the visible chunks.
    • There is no notion of threading. The API is a collection of free functions which the user may call from appropriate threads. Blast™ guarantees that it is safe to operate on different actors from different threads.
    • There is no global memory manager, message handler, etc. All low-level API functions take an optional message function pointer argument in order to report warnings or errors. Memory is managed by the user, and functions that build objects require an appropriately-sized memory block to be passed in. A corresponding utility function that calculates the memory requirements is always present alongside such functions. Temporary storage needed by a function is always handled via user-supplied scratch space. For scratch, there is always a corresponding "RequiredScratch" function or documentation which lets the user know how much scratch space is needed based upon the function arguments.
    • Backwards-compatible, versioned, device-independent serialization is not handled by Blast™. There is< > however a Blast™ extension which does, see Serialization (NvBlastExtSerialization). However, a simple form of serialization may be performed on assets and familes (see Definitions) via simple memory copy. The data associated with these objects is available to the user, and may be copied and stored by the user. There are Simply casting a pointer to such a block of memory to the correct object type will produce a usable object for Blast™. (The only restriction is that the block must be 16-byte aligned.) Families contain a number of actors and so this form of deserialization recreates all actors in the family. This form of serialization may be used between two devices which have the same endianness, and contain Blast™ SDKs which use the same object format.
    • Single-actor serialization and deserialization is, however, supported. This is not as light-weight as family serialization, but may be a better serialization model for a particular application. To deserialize a single actor, one must have a family to hold the actor, created from the appropriate asset. If none exists already, the user may create an empty family. After that, all actors that had been in that family may be deserialized into it one-at-a-time, in any order.
    +
  • There is no physics representation. The low-level API is agnostic with respect to any physics engine, and furthermore does not have any notion of collision geometry. The NvBlastActor is an abstraction which is intended to correspond to a rigid body. However it is up to the user to implement that connection. The NvBlastActor references a list of visible chunk indices, which correspond to NvBlastChunk data in the asset. The NvBlastChunk contains a userData field which can be used to associate collision geometry with the actor based upon the visible chunks. The same is true for constraints created between actors. Bonds contain a userData field that can be used to inform the user that actors should have joints created at a particular location, but it is up to the user to create and manage physical joints between two actors.
  • There is no graphics representation. Just as there is no notion of collision geometry, there is also no notion of graphics geometry. The NvBlastChunk userData field (see the item above) can be used to associate graphics geometry with the actor based upon the visible chunks.
  • There is no notion of threading. The API is a collection of free functions which the user may call from appropriate threads. Blast™ guarantees that it is safe to operate on different actors from different threads.
  • There is no global memory manager, message handler, etc. All low-level API functions take an optional message function pointer argument in order to report warnings or errors. Memory is managed by the user, and functions that build objects require an appropriately-sized memory block to be passed in. A corresponding utility function that calculates the memory requirements is always present alongside such functions. Temporary storage needed by a function is always handled via user-supplied scratch space. For scratch, there is always a corresponding "RequiredScratch" function or documentation which lets the user know how much scratch space is needed based upon the function arguments.
  • Backwards-compatible, versioned, device-independent serialization is not handled by Blast™. There is however a Blast™ extension which does, see Serialization (NvBlastExtSerialization). However, a simple form of serialization may be performed on assets and familes (see Definitions) via simple memory copy. The data associated with these objects is available to the user, and may be copied and stored by the user. Simply casting a pointer to such a block of memory to the correct object type will produce a usable object for Blast™. (The only restriction is that the block must be 16-byte aligned.) Families contain a number of actors and so this form of deserialization recreates all actors in the family. This form of serialization may be used between two devices which have the same endianness, and contain Blast™ SDKs which use the same object format.
  • Single-actor serialization and deserialization is, however, supported. This is not as light-weight as family serialization, but may be a better serialization model for a particular application. To deserialize a single actor, one must have a family to hold the actor, created from the appropriate asset. If none exists already, the user may create an empty family. After that, all actors that had been in that family may be deserialized into it one-at-a-time, in any order.
  • -
    -

    +
    +

    Linking and Header Files

    - To use the low-level Blast™ SDK, the application need only inlclude the header NvBlast.h, found in the top-level include folder, and link against the appropriate version of the NvBlast library. Depending on the platform and configuration, various suffixes will be added to the library name. The general naming scheme is

    -NvBlast(config)(arch).(ext)

    -(config) is DEBUG, CHECKED, OR PROFILE for the corresponding configurations. For a release configuration there is no (config) suffix.

    -(arch) is _x86 or _x64 for Windows 32- and 64-bit builds, respectively, and empty for non-Windows platforms.

    -(ext) is .lib for static linking and .dll for dynamic linking on Windows. On XBoxOne it is .lib, and on PS4 it is .a.

    -
    -

    +To use the low-level Blast™ SDK, the application need only inlclude the header NvBlast.h, found in the top-level include folder, and link against the appropriate version of the NvBlast library. Depending on the platform and configuration, various suffixes will be added to the library name. The general naming scheme is

    +NvBlast(config)(arch).(ext)

    +(config) is DEBUG, CHECKED, OR PROFILE for the corresponding configurations. For a release configuration there is no (config) suffix.

    +(arch) is _x86 or _x64 for Windows 32- and 64-bit builds, respectively, and empty for non-Windows platforms.

    +(ext) is .lib for static linking and .dll for dynamic linking on Windows. On XBoxOne it is .lib, and on PS4 it is .a.

    +
    +

    Creating an Asset from a Descriptor (Authoring)

    - The NvBlastAsset is an opaque type pointing to an object constructed by Blast™ in memory allocated by the user. To create an asset from a descriptor, use the function NvBlastAssetCreate. See the function documentation for a description of its parameters.

    -N.B., there are strict rules for the ordering of chunks with an asset, and also conditions on the chunks marked as "support" (using the NvBlastChunkDesc::SupportFlag). See the function documentation for these conditions. NvBlastAssetCreate does not reorder chunks or modify support flags to meet these conditions. If the conditions are not met, NvBlastAssetCreate fails and returns NULL. However, Blast™ provides helper functions to reorder chunk descriptors and modify the support flags within those descriptors so that they are valid for asset creation. The helper functions return a mapping from the original chunk ordering to the new chunk ordering, so that corresponding adjustments or mappings may be made for graphics and other data the user associates with chunks.

    -Example code is given below. Throughout, we assume the user has defined a logging function called logFn, with the signature of NvBlastLog. In all cases, the log function is optional, and NULL may be passed in its place.

    -

    // Create chunk descriptors
    +The NvBlastAsset is an opaque type pointing to an object constructed by Blast™ in memory allocated by the user. To create an asset from a descriptor, use the function NvBlastCreateAsset. See the function documentation for a description of its parameters.

    +N.B., there are strict rules for the ordering of chunks with an asset, and also conditions on the chunks marked as "support" (using the NvBlastChunkDesc::SupportFlag). See the function documentation for these conditions. NvBlastCreateAsset does not reorder chunks or modify support flags to meet these conditions. If the conditions are not met, NvBlastCreateAsset fails and returns NULL. However, Blast™ provides helper functions to reorder chunk descriptors and modify the support flags within those descriptors so that they are valid for asset creation. The helper functions return a mapping from the original chunk ordering to the new chunk ordering, so that corresponding adjustments or mappings may be made for graphics and other data the user associates with chunks.

    +Example code is given below. Throughout, we assume the user has defined a logging function called logFn, with the signature of NvBlastLog. In all cases, the log function is optional, and NULL may be passed in its place.

    +

    // Create chunk descriptors
     std::vector<NvBlastChunkDesc> chunkDescs;
     chunkDescs.resize( chunkCount );    // chunkCount > 0
     
     chunkDescs[0].parentChunkIndex = UINT32_MAX;    // invalid index denotes a chunk hierarchy root
    -chunkDescs[0].centroid[0] = 0.f;    // centroid position in asset-local space
    -chunkDescs[0].centroid[1] = 0.f;
    -chunkDescs[0].centroid[2] = 0.f;
    -chunkDescs[0].volume = 1.f; // Unit volume
    +chunkDescs[0].centroid[0] = 0.0f;   // centroid position in asset-local space
    +chunkDescs[0].centroid[1] = 0.0f;
    +chunkDescs[0].centroid[2] = 0.0f;
    +chunkDescs[0].volume = 1.0f;    // Unit volume
     chunkDescs[0].flags = NvBlastChunkDesc::NoFlags;
    -chunkDescs[0].ID = 0;   // User-supplied ID.  For example, this can be the index of the chunkDesc.
    -                        // The ID can be left undefined.
    +chunkDescs[0].userData = 0; // User-supplied ID.  For example, this can be the index of the chunkDesc.
    +                            // The userData can be left undefined.
     
     chunkDescs[1].parentChunkIndex = 0; // child of chunk described by chunkDescs[0]
    -chunkDescs[1].centroid[0] = 2.f;    // centroid position in asset-local space
    -chunkDescs[1].centroid[1] = 4.f;
    -chunkDescs[1].centroid[2] = 6.f;
    -chunkDescs[1].volume = 1.0; // Unit volume
    +chunkDescs[1].centroid[0] = 2.0f;   // centroid position in asset-local space
    +chunkDescs[1].centroid[1] = 4.0f;
    +chunkDescs[1].centroid[2] = 6.0f;
    +chunkDescs[1].volume = 1.0f;    // Unit volume
     chunkDescs[1].flags = NvBlastChunkDesc::SupportFlag; // This chunk should be represented in the support graph
    -chunkDescs[1].ID = 1;
    +chunkDescs[1].userData = 1;
     
     // ... etc. for all chunks
     
    @@ -76,14 +76,14 @@ bondDescs.resize( bondCount );  // bondCount > 0
     
     bondDescs[0].chunkIndices[0] = 1;   // chunkIndices refer to chunk descriptor indices for support chunks
     bondDescs[0].chunkIndices[1] = 2;
    -bondDescs[0].bond.m_normal[0] = 1.f;    // normal in the +x direction
    -bondDescs[0].bond.m_normal[1] = 0.f;
    -bondDescs[0].bond.m_normal[2] = 0.f;
    -bondDescs[0].bond.m_area = 1.0; // unit area
    -bondDescs[0].bond.m_centroid[0] = 1.f;  // centroid position in asset-local space
    -bondDescs[0].bond.m_centroid[1] = 2.f;
    -bondDescs[0].bond.m_centroid[2] = 3.f;
    -bondDescs[0].m_userData = 0;    // this can be used to tell the user more information about this
    +bondDescs[0].bond.normal[0] = 1.0f; // normal in the +x direction
    +bondDescs[0].bond.normal[1] = 0.0f;
    +bondDescs[0].bond.normal[2] = 0.0f;
    +bondDescs[0].bond.area = 1.0f;  // unit area
    +bondDescs[0].bond.centroid[0] = 1.0f;   // centroid position in asset-local space
    +bondDescs[0].bond.centroid[1] = 2.0f;
    +bondDescs[0].bond.centroid[2] = 3.0f;
    +bondDescs[0].userData = 0;  // this can be used to tell the user more information about this
                                     // bond for example to create a joint when this bond breaks
     
     bondDescs[1].chunkIndices[0] = 1;
    @@ -109,37 +109,37 @@ std::vector<uint32_t> map(chunkCount);  // Will be f
     scratch.resize( NvBlastGetRequiredScratchForCreateAsset( &assetDesc ) );    // Provide scratch memory for asset creation
     void* mem = malloc( NvBlastGetAssetMemorySize( &assetDesc ) );      // Allocate memory for the asset object
     NvBlastAsset* asset = NvBlastCreateAsset( mem, &assetDesc, scratch.data(), logFn );
    -

    -
    - It should be noted that the geometric information (centroid, volume, area, normal) in chunks and bonds is only used by damage shader functions (see Damage Shaders (NvBlastExtShaders)). Depending on the shader, some, all, or none of the geometric information will be needed. The user may write damage shader functions that interpret this data in any way they wish.

    -
    -

    +

    +
    + It should be noted that the geometric information (centroid, volume, area, normal) in chunks and bonds is only used by damage shader functions (see
    Damage Shaders (NvBlastExtShaders)). Depending on the shader, some, all, or none of the geometric information will be needed. The user may write damage shader functions that interpret this data in any way they wish.

    +
    +

    Cloning an Asset

    - To clone an asset, one only needs to copy the memory associated with the NvBlastAsset.

    -

    uint32_t assetSize = NvBlastAssetGetSize( asset );
    +To clone an asset, one only needs to copy the memory associated with the NvBlastAsset.

    +

    uint32_t assetSize = NvBlastAssetGetSize( asset );
     
     NvBlastAsset* newAsset = (NvBlastAsset*)malloc(assetSize);  // NOTE: the memory buffer MUST be 16-byte aligned!
     memcpy( newAsset, asset, assetSize );   // this data may be copied into a buffer, stored to a file, etc.
    -

    -N.B. the comment after the malloc call above. NvBlastAsset memory must be 16-byte aligned.

    -
    -

    +

    +N.B. the comment after the malloc call above. NvBlastAsset memory must be 16-byte aligned.

    +
    +

    Releasing an Asset

    - Blast&tm low-level does no internal allocation; since the memory is allocated by the user, one simply has to free the memory they've allocated. The asset pointer returned by NvBlastCreateAsset has the same numerical value as the mem block passed in (if the function is successful, or NULL otherwise). So releasing an asset with memory allocate by malloc is simply done with a call to free:

    -

    free( asset );
    -

    -
    -

    +Blast™ low-level does no internal allocation; since the memory is allocated by the user, one simply has to free the memory they've allocated. The asset pointer returned by NvBlastCreateAsset has the same numerical value as the mem block passed in (if the function is successful, or NULL otherwise). So releasing an asset with memory allocated by malloc is simply done with a call to free:

    +

    free( asset );
    +

    +
    +

    Creating Actors and Families

    - Actors live within a family created from asset data. To create an actor, one must first create a family. This family is used by the initial actor created from the asset, as well as all of the descendent actors created by recursively fracturing the initial actor. As with assets, family allocation is done by the user.

    -To create a family, use:

    -

    // Allocate memory for the family object - this depends on the asset being represented by the family.
    +Actors live within a family created from asset data. To create an actor, one must first create a family. This family is used by the initial actor created from the asset, as well as all of the descendant actors created by recursively fracturing the initial actor. As with assets, family allocation is done by the user.

    +To create a family, use:

    +

    // Allocate memory for the family object - this depends on the asset being represented by the family.
     void* mem = malloc( NvBlastAssetGetFamilyMemorySize( asset, logFn ) );
     
     NvBlastFamily* family = NvBlastAssetCreateFamily( mem, asset, logFn );
    -

    -When an actor is first created from an asset, it represents the root of the chunk hierarchy, that is the unfractured object. To create this actor, use:

    -

    // Set the fields of the descriptor
    +

    +When an actor is first created from an asset, it represents the root of the chunk hierarchy, that is the unfractured object. To create this actor, use:

    +

    // Set the fields of the descriptor
     NvBlastActorDesc actorDesc;
     actorDesc.asset = asset;    // point to a valid asset
     actorDesc.initialBondHealth = 1.0f;  // this health value will be given to all bonds
    @@ -150,83 +150,83 @@ std::vector<char> scratch( // Create the first actor
     NvBlastActor* actor = NvBlastFamilyCreateFirstActor( family, &actorDesc, scratch.data(), logFn );   // ready to be associated with physics and graphics by the user
    -

    -
    -

    +

    +
    +

    Copying Actors (Serialization and Deserialization)

    - There are two ways to copy NvBlastActors: cloning an NvBlastFamily, and single-actor serialization. Cloning an NvBlastFamily is extremely fast as it only requires a single memory copy. All actors in the family may be saved, loaded, or copied at once in this way.

    -
    -

    +There are two ways to copy NvBlastActors: cloning an NvBlastFamily, and single-actor serialization. Cloning an NvBlastFamily is extremely fast as it only requires a single memory copy. All actors in the family may be saved, loaded, or copied at once in this way.

    +
    +

    Cloning a Family

    - To clone a family, use the family pointer which may be retrieved from any active actor in the family if needed, using the NvBlastActorGetFamily function:

    -

    const NvBlastFamily* family = NvBlastActorGetFamily( &actor, logFn );
    -

    -Then the size of the family may be obtained using:

    -

    size_t size = NvBlastFamilyGetSize( family, logFn );
    -

    -Now this memory may be copied, saved to disk, etc. To clone the family, for example, we can duplicate the memory:

    -

    std::vector<char> buffer( size );
    +To clone a family, use the family pointer which may be retrieved from any active actor in the family if needed, using the NvBlastActorGetFamily function:

    +

    const NvBlastFamily* family = NvBlastActorGetFamily( &actor, logFn );
    +

    +Then the size of the family may be obtained using:

    +

    size_t size = NvBlastFamilyGetSize( family, logFn );
    +

    +Now this memory may be copied, saved to disk, etc. To clone the family, for example, we can duplicate the memory:

    +

    std::vector<char> buffer( size );
     NvBlastFamily* family2 = reinterpret_cast<NvBlastFamily*>( buffer.data() );
     memcpy( family2, family, size );
    -

    -N.B. If this data has been serialized from an external source, the family will not contain a valid reference to its associated asset. The user must set the family's asset. The family does however contain the asset's ID, to help the user match the correct asset to the family. So one way of restoring the asset to the family follows:

    -

    const NvBlastGUID guid = NvBlastFamilyGetAssetID( family2, logFn );
    +

    +N.B. If this data has been serialized from an external source, the family will not contain a valid reference to its associated asset. The user must set the family's asset. The family does however contain the asset's ID, to help the user match the correct asset to the family. So one way of restoring the asset to the family follows:

    +

    const NvBlastGUID guid = NvBlastFamilyGetAssetID( family2, logFn );
     // ... here the user must retrieve the asset using the GUID or by some other means
     NvBlastFamilySetAsset( family2, asset, logFn );
    -

    -The data in family2 will contain the same actors as the original family. To access them, use:

    -

    uint32_t actorCount = NvBlastFamilyGetActorCount( family2, logFn );
    +

    +The data in family2 will contain the same actors as the original family. To access them, use:

    +

    uint32_t actorCount = NvBlastFamilyGetActorCount( family2, logFn );
     std::vector<NvBlastActor*> actors( actorCount );
     uint32_t actorsWritten = NvBlastFamilyGetActors( actors.data(), actorCount, family2, logFn );
    -

    -In the code above, actorsWritten should equal actorCount.

    -
    -

    +

    +In the code above, actorsWritten should equal actorCount.

    +
    +

    Single Actor Serialization

    - To perform single-actor serialization, first find the buffer size required to store the serialization data:

    -

    size_t bufferSize = NvBlastActorGetSerializationSize( actor, logFn );
    -

    -If you want to use an upper bound which will be large enough for any actor in a family, you may use:

    -

    size_t bufferSize = NvBlastAssetGetActorSerializationSizeUpperBound( asset, logFn );
    -

    -Then create a buffer of that size and use NvBlastActorSerialize to write to the buffer:

    -

    std::vector<char> buffer( bufferSize );
    +To perform single-actor serialization, first find the buffer size required to store the serialization data:

    +

    size_t bufferSize = NvBlastActorGetSerializationSize( actor, logFn );
    +

    +If you want to use an upper bound which will be large enough for any actor in a family, you may use:

    +

    size_t bufferSize = NvBlastAssetGetActorSerializationSizeUpperBound( asset, logFn );
    +

    +Then create a buffer of that size and use NvBlastActorSerialize to write to the buffer:

    +

    std::vector<char> buffer( bufferSize );
     size_t bytesWritten = NvBlastActorSerialize( buffer, bufferSize, actor, logFn );
    -

    -To deserialize the buffer, an appropriate family must be created. It must not already hold a copy of the actor. It must be formed using the correct asset (the one that originally created the actor):

    -

    void* mem = malloc( NvBlastAssetGetFamilyMemorySize( asset, logFn ) );
    +

    +To deserialize the buffer, an appropriate family must be created. It must not already hold a copy of the actor. It must be formed using the correct asset (the one that originally created the actor):

    +

    void* mem = malloc( NvBlastAssetGetFamilyMemorySize( asset, logFn ) );
     NvBlastFamily* family = NvBlastAssetCreateFamily( mem, asset, logFn );
    -

    -Then deserialize into the family:

    -

    NvBlastActor* newActor = NvBlastFamilyDeserializeActor( family, buffer.data(), logFn );
    -

    -If newActor is not NULL, then the actor was successfully deserialized.

    -
    -

    +

    +Then deserialize into the family:

    +

    NvBlastActor* newActor = NvBlastFamilyDeserializeActor( family, buffer.data(), logFn );
    +

    +If newActor is not NULL, then the actor was successfully deserialized.

    +
    +

    Deactivating an Actor

    - Actors may not be released in the usual sense of deallocation. This is because actors' memory is stored as a block within the owning family. The memory is only released when the family is released. However, one may deactivate an actor using NvBlastActorDeactivate. This clears the actor's chunk lists and marks it as invalid, effectively disassociating it from the family. The user should consider this actor to be destroyed.

    -

    bool success = NvBlastActorDeactivate( actor, logFn );
    -

    -
    -

    +Actors may not be released in the usual sense of deallocation. This is because actors' memory is stored as a block within the owning family. The memory is only released when the family is released. However, one may deactivate an actor using NvBlastActorDeactivate. This clears the actor's chunk lists and marks it as invalid, effectively disassociating it from the family. The user should consider this actor to be destroyed.

    +

    +
    +

    Releasing a family

    - As mentioned above, releasing an actor does not actually do any deallocation; it simply invalidates the actor within its family. To actually deallocate memory, you must deallocate the family. Note, this will invalidate all actors in the family. This is a fast way to delete all actors that were created from repeated fracturing of a single instance. As with NvBlastAsset, memory is allocated by the user, so to release a family with memory allocated by malloc, simply free that memory with free:

    -

    free( family );
    -

    -The family will not be automatically released when all actors within it are invalidated using NvBlastActorDeactivate. However, the user may query the number of active actors in a family using

    -

    uint32_t actorCount = NvBlastFamilyGetActorCount( family, logFn );
    -

    -
    -

    +As mentioned above, releasing an actor does not actually do any deallocation; it simply invalidates the actor within its family. To actually deallocate memory, you must deallocate the family. Note, this will invalidate all actors in the family. This is a fast way to delete all actors that were created from repeated fracturing of a single instance. As with NvBlastAsset, memory is allocated by the user, so to release a family with memory allocated by malloc, simply free that memory with free:

    +

    free( family );
    +

    +The family will not be automatically released when all actors within it are invalidated using NvBlastActorDeactivate. However, the user may query the number of active actors in a family using

    +

    uint32_t actorCount = NvBlastFamilyGetActorCount( family, logFn );
    +

    +
    +

    Damage and Fracturing

    - Damaging and fracturing is a staged process. In a first step, a NvBlastDamageProgram creates lists of Bonds and Chunks to damage - so called Fracture Commands. The lists are created from input specific to the NvBlastDamageProgram.
    +Damaging and fracturing is a staged process. In a first step, a NvBlastDamageProgram creates lists of Bonds and Chunks to damage - so called Fracture Commands. The lists are created from input specific to the NvBlastDamageProgram.
    NvBlastDamagePrograms are composed of a NvBlastGraphShaderFunction and a NvBlastSubgraphShaderFunction operating on support graphs (support chunks and bonds) and disconnected subsupport chunks respectively. An implementer can freely define the shader functions and parameters. Different functions can have the effect of emulating different physical materials.
    - Blast™ provides reference implementations of such functions in Damage Shaders (NvBlastExtShaders), see also NvBlastExtDamageShaders.h. The NvBlastDamageProgram is used through NvBlastActorGenerateFracture that will provide the necessary internal data for the NvBlastActor being processed. The shader functions see the internal data as NvBlastGraphShaderActor and NvBlastSubgraphShaderActor respectively.

    -The second stage is carried out with NvBlastActorApplyFracture. This function takes the previously generated Fracture Commands and applies them to the NvBlastActor. The result of every applied command is reported as a respective Fracture Event if requested.

    -Fracture Commands and Fracture Events both are represented by NvBlastFractureBuffers. The splitting of the actor into child actors is not done until the third stage, NvBlastActorSplit, is called. Fractures may be repeatedly applied to an actor before splitting.

    -The NvBlastActorGenerateFracture, NvBlastActorApplyFracture and NvBlastActorSplit functions are profiled in Profile configurations. This is done through a pointer to a NvBlastTimers struct passed into the functions. If this pointer is not NULL, then timing values will be accumulated in the referenced struct.

    -The following example illustrates the process:

    -

    // Step one: Generate Fracture Commands
    + Blast™ provides reference implementations of such functions in Damage Shaders (NvBlastExtShaders), see also NvBlastExtDamageShaders.h. The NvBlastDamageProgram is used through NvBlastActorGenerateFracture that will provide the necessary internal data for the NvBlastActor being processed. The shader functions see the internal data as NvBlastGraphShaderActor and NvBlastSubgraphShaderActor respectively.

    +The second stage is carried out with NvBlastActorApplyFracture. This function takes the previously generated Fracture Commands and applies them to the NvBlastActor. The result of every applied command is reported as a respective Fracture Event if requested.

    +Fracture Commands and Fracture Events both are represented by NvBlastFractureBuffers. The splitting of the actor into child actors is not done until the third stage, NvBlastActorSplit, is called. Fractures may be repeatedly applied to an actor before splitting.

    +The NvBlastActorGenerateFracture, NvBlastActorApplyFracture and NvBlastActorSplit functions are profiled in Profile configurations. This is done through a pointer to a NvBlastTimers struct passed into the functions. If this pointer is not NULL, then timing values will be accumulated in the referenced struct.

    +The following example illustrates the process:

    +

    // Step one: Generate Fracture Commands
     
     // Damage programs (shader functions), material properties and damage description relate to each other.
     // Together they define how actors will break by generating the desired set of Fracture Commands for Bonds and Chunks.
    @@ -248,7 +248,7 @@ Damage and Fracturing

    // Step three: Splitting // The Actor may be split into all its smallest pieces. -uint32_t maxNewActorCount = NvBlastAssetGetChunkCount( asset, logFn ); // In the worst case, one NvBlastActor may be created for every chunk in the asset +uint32_t maxNewActorCount = NvBlastActorGetMaxActorCountForSplit( actor, logFn ); std::vector<NvBlastActor*> newActors( maxNewActorCount ); // Make this memory available to NvBlastSplitEvent. @@ -261,9 +261,9 @@ std::vector<char> scratch( // New actors created are reported in splitEvent.newActors. // If newActorCount != 0, then the old actor is deleted and is reported in splitEvent.deletedActor. size_t newActorCount = NvBlastActorSplit( &splitEvent, actor, maxNewActorCount, scratch.data(), logFn, &timers ); -

    -
    -
    +

    +
    +

    Running the application with no commandline arguments, the viewer will load samples/resources/configs/assets.xml by default. This file references the models in the subdirectories of samples/resources/models.

    Using SampleAssetViewer

    -Upon startup, the viewer will instance its first asset in its assets list. Using the default assets.xml, this is a brick will.

    +Upon startup, the viewer will instance its first asset in its assets list. Using the default assets.xml, this is a brick wall.

    The menu is displayed using an overlay on the left side of the screen. It is divided into many submenus, which are described below.

    -In any scene, you may press 'F' to fire a box into the scene in the direction the camer is pointing.

    +In any scene, you may press 'F' to fire a box into the scene in the direction the camera is pointing.

    You may also press SPACE to toggle between damage and drag mode. (The mode is shown at the top of the screen.) In drag mode, dynamic objects can be manipulated by placing the mouse cursor over them, and using Left Mouse / Drag to pull on the object. In damage mode, left-clicking a destructible actor will apply damage to it.

    You may select between three different damage tools using the 1, 2, and 3 keys. Each will color the damage sphere (shown at the mouse hit location) a different color:

      @@ -52,17 +52,19 @@ Scene

    Here you can select which assets to add to the scene, set the material damage properties, and enable a stress solver.

    In Replace mode (the default, set by radio button), selecting assets in the Assets list will remove all destructible actors from the scene and insert the selected one. In Append mode (the other radio button), selecting a new asset will insert its actor into the scene while keeping the others as well.

    You may also select actors in the Scene Actors list, and remove (or reload) the actor using the buttons below the list. Reloading an actor will restore it to its unfractured state.

    -Note, in addition to destructible actors, the Scene Actors list shows the boxes that were fired into the scene using the 'F' key. Holding down the 'F' key "charges" the throw, increasing the cube's speed the longer you hold down the kye. You may remove the cubes using the scene controls. All cubes will be removed when the scene is reset.

    +Note, in addition to destructible actors, the Scene Actors list shows the boxes that were fired into the scene using the 'F' key. Holding down the 'F' key "charges" the throw, increasing the cube's speed the longer you hold down the key. You may remove the cubes using the scene controls. All cubes will be removed when the scene is reset.

    The Blast Material properties are used by the various damage tools available.

    • Health = the value which damage must exceed to break a bond or chunk
    • Min Damage Threshold = a fraction of Health, below which damage has no effect
    • Max Damage Threshold = a fraction of Health, equal to the maximum damage that can be applied per damage event

    -A stress solver may be enabled by selcting the Stress Solver Enabled checkbox. When enabled you will be presented with several options. NOTE: you must then select the Stress Damage Enabled checkbox in order to allow stress to do damage to the actors in the scene. Bond Iterations Per Frame - is max amount of bonds allowed to be processed in one frame. The more this value the better quality of stress solver, but the time taken by it is increased linearly. You can check this timing in Stats submenu. Using this value stress solver takes fixed amount of CPU time on asset of any size. So the more asset complex (the more bonds it has) the less total iterations (on all bonds) are made. Use graph reduction level param to simplify stress graph for large assets. You can look at stress graph using by using Debug Render submenu. Stress linear and angular factors are corresponded for amount of damage to be applied on bonds from linear and angular momentum of stress on every bond.

    -Replay control section allows to control recording and replaying Blast events. It demonstrates the usage of ExtSync extension. You may start/stop recording of blast events (damage, split). If you toggle to sync initial actors once recording starts full blast state is saved.

    +A stress solver may be enabled by selcting the Stress Solver Enabled checkbox. When enabled, you will be presented with several options. NOTE: you must then select the Stress Damage Enabled checkbox in order to allow stress to do damage to the actors in the scene.
    + Bond Iterations Per Frame - is max amount of bonds allowed to be processed in one frame. The higher this value, the better quality of stress solver, but the time taken by it is increased linearly. 9You can check this timing in Stats submenu.) Using this value stress solver takes a fixed amount of CPU time on assets of any size. So the more complex an asset is (the more bonds it has) the less total iterations (on all bonds) are made.
    + Use graph reduction level param to simplify stress graph for large assets. You can look at stress graph by using the Debug Render submenu. Stress linear and angular factors are corresponded to the amount of damage to be applied on bonds from linear and angular momentum of stress on every bond.

    +Replay control section allows to control recording and replaying Blast™ events. It demonstrates the usage of ExtSync extension. You may start/stop recording of Blast™ events (damage, split). If you toggle to sync initial actors, once recording starts, the full Blast™ state is saved.

    Blast

    Here you may disable or enable impact damage, using the Impact Damage checkbox (on by default).

    The Fragility setting is a multiplier that turns impact forces into damage amounts.

    -You can toggle to pass impact damage to stress solver instead of just applying it with simple damage shader. Impact impulse will be passed to stress graph and damage will be applied accordingly to stress solver settings mentioned above.

    +You can toggle to pass impact damage to stress solver instead of just applying it with simple damage shader. Impact impulse will be passed to stress graph and damage will be applied according to stress solver settings mentioned above.

    When dragging static actors (with mouse dragging tool) stress impulse is also applied on stress graph. Use Dragging To Stress Factor to tune the amount.

    You can limit rigid body count with next setting, all the actors created above this count will be ignored.

    Damage Tool

    @@ -82,7 +84,7 @@ You may select the debug render options from the Blast Debug Render Mode dropdow
  • Disabled = no debug rendering
  • Health Graph = draws bonds with color based upon bond health. Green = full health, red = low health.
  • Centroids = draws a line segment starting at each bond centroid, pointing in the direction of the bond normal. Also draws a square centered at the bond centroid, with the area of the bond.
  • Health Graph + Centroids = the two options above, combined.
  • Stress Graph = draws bonds with color based upon stress values. Green = low stress, red = high stress.
  • Stress Graph + Nodes Impulse = same as Stress Graph plus a line segment indicating the impulse applied to each graph node. The length of the segment is scaled by the Blast Debug Render Scale control. The green segments show the linear impulse, the red segments the rotational impulse.
  • Stress Graph + Bonds Impulse = same as Stress Graph plus a line segment indicating the impulse applied to each bond. The length of the segment is scaled by the Blast Debug Render Scale control. The green segments show the linear impulse, the red segments the rotational impulse.
  • PhysX

    -This menu controls PhysX simulation parameters. Here you may choose to use fixed time steps (off by default), and set the time step (if Use Fixed Timestep is checked) with the Fixed Timestep control.

    +This menu controls PhysX™ simulation parameters. Here you may choose to use fixed time steps (off by default), and set the time step (if Use Fixed Timestep is checked) with the Fixed Timestep control.

    If a suitable GPU is available, GPU Physics may be enabled using the Use GPU Physics control.

    Renderer

    Here you may change the lighting, shadow, and ambient occlusion (HBAO) options.

    diff --git a/docs/api_docs/files/pagetools.html b/docs/api_docs/files/pagetools.html index 6fb1a86..574433f 100644 --- a/docs/api_docs/files/pagetools.html +++ b/docs/api_docs/files/pagetools.html @@ -23,7 +23,7 @@

    Tools


    See Copyrights for license information regarding third-party software used by the tools.


    - ApexImporter - Import Apex assets into Blast format.

    + ApexImporter - Import Apex assets into Blast™ format.


    AuthoringTool - Command line authoring tool.


    diff --git a/docs/api_docs/files/struct_nv_1_1_blast_1_1_authoring_result.html b/docs/api_docs/files/struct_nv_1_1_blast_1_1_authoring_result.html index e968584..b5843b1 100644 --- a/docs/api_docs/files/struct_nv_1_1_blast_1_1_authoring_result.html +++ b/docs/api_docs/files/struct_nv_1_1_blast_1_1_authoring_result.html @@ -303,7 +303,7 @@ Size of array of material names.

    -Array of material names. +Array of material names.

    @@ -318,7 +318,7 @@ Size of array of material names.

    -Array of chunk physics parameters. Contains chunkCount elements +Array of chunk physics parameters. Contains chunkCount elements

    @@ -333,7 +333,7 @@ Size of array of material names.

    -Array of phisics subchunks (convex mesh) descriptors. Use collisionHullOffset for accessing elements. +Array of phisics subchunks (convex mesh) descriptors. Use collisionHullOffset for accessing elements.


    The documentation for this struct was generated from the following file: