Blast 1.1 release (windows / linux)

see docs/release_notes.txt for details

1 files changed, 117 insertions, 40 deletions

diff --git a/sdk/toolkit/include/NvBlastTkGroup.h b/sdk/toolkit/include/NvBlastTkGroup.h
index 585cccb..2e5ee3e 100644
--- a/sdk/toolkit/include/NvBlastTkGroup.h
+++ b/sdk/toolkit/include/NvBlastTkGroup.h
@@ -1,12 +1,30 @@
-/*
-* Copyright (c) 2016-2017, NVIDIA CORPORATION.  All rights reserved.
-*
-* NVIDIA CORPORATION and its licensors retain all intellectual property
-* and proprietary rights in and to this software, related documentation
-* and any modifications thereto.  Any use, reproduction, disclosure or
-* distribution of this software and related documentation without an express
-* license agreement from NVIDIA CORPORATION is strictly prohibited.
-*/
+// This code contains NVIDIA Confidential Information and is disclosed to you
+// under a form of NVIDIA software license agreement provided separately to you.
+//
+// Notice
+// NVIDIA Corporation and its licensors retain all intellectual property and
+// proprietary rights in and to this software and related documentation and
+// any modifications thereto. Any use, reproduction, disclosure, or
+// distribution of this software and related documentation without an express
+// license agreement from NVIDIA Corporation is strictly prohibited.
+//
+// ALL NVIDIA DESIGN SPECIFICATIONS, CODE ARE PROVIDED "AS IS.". NVIDIA MAKES
+// NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO
+// THE MATERIALS, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT,
+// MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.
+//
+// Information and code furnished is believed to be accurate and reliable.
+// However, NVIDIA Corporation assumes no responsibility for the consequences of use of such
+// information or for any infringement of patents or other rights of third parties that may
+// result from its use. No license is granted by implication or otherwise under any patent
+// or patent rights of NVIDIA Corporation. Details are subject to change without notice.
+// This code supersedes and replaces all information previously supplied.
+// NVIDIA Corporation products are not authorized for use as critical
+// components in life support devices or systems without express written approval of
+// NVIDIA Corporation.
+//
+// Copyright (c) 2016-2017 NVIDIA Corporation. All rights reserved.
+
 
 #ifndef NVBLASTTKGROUP_H
 #define NVBLASTTKGROUP_H
@@ -14,13 +32,6 @@
 #include "NvBlastTkIdentifiable.h"
 
 
-// Forward declarations
-namespace physx
-{
-class PxTaskManager;
-}
-
-
 namespace Nv
 {
 namespace Blast
@@ -31,12 +42,12 @@ class TkActor;
 
 
 /**
-Descriptor for a TkGroup.  It uses the PxShared PxTaskManager interface to dispatch PxLightCpuTask.
-@see TkWorker
+Descriptor for a TkGroup.  TkGroup uses a number of TkGroupWorker to process its actors.
+@see TkGroupWorker, TkGroup::setWorkerCount
 */
 struct TkGroupDesc
 {
-	physx::PxTaskManager* pxTaskManager;	//!< User-defined task manager
+	uint32_t		workerCount;			//!< The number of expected TkWorkers to process the TkGroup concurrently.
 };
 
 
@@ -53,14 +64,39 @@ struct TkGroupStats
 
 
 /**
+A worker as provided by TkGroup::acquireWorker(). It manages the necessary memory for parallel processing.
+The group can be processed concurrently by calling process() from different threads using a different TkGroupWorker each.
+
+TkActors that have been damaged with applyFracture() such that they may be split into separate
+actors are split by this function. TkActors that have damage queued through the actor's damage() function
+will be fractured and split by this function.
+*/
+class TkGroupWorker
+{
+public:
+	/**
+	Process a job of this worker's TkGroup.
+
+	/param[in]	jobId	a job id in the range (0, TkGroup::startProcess()]
+	*/
+	virtual void	process(uint32_t jobId) = 0;
+};
+
+
+/**
 A group is a processing unit, to which the user may add TkActors.  New actors generated from splitting a TkActor
 are automatically put into the same group.  However, any actor may be removed from its group and placed into
 another group (or no group) by the user's choice.
 
 When the group's process function is called, all actors' damage buffers will be processed and turned into fracture events
 and the actor is split if applicable.
-This work is done in separate (possibly multiple) threads.  The sync function waits for the processing threads to finish
-and dispatches events for processing that actually occurred.
+
+This work can be done in multiple threads with the help of TkGroupWorker:  
+Instead of calling the process function, commence the procedure with startProcess which returns the number of jobs to process.  
+Each concurrent thread uses an acquired TkGroupWorker to process the jobs.
+Over the whole procedure, each job must be processed once and only once.  
+Jobs can be processed in any order.  TkGroupWorkers can be returned and acquired later by another task.
+After processing every job and returning all the workers to the group, endProcess concludes the procedure.
 */
 class TkGroup : public TkIdentifiable
 {
@@ -72,14 +108,14 @@ public:
 
 	\return true if successful, false otherwise.
 	*/
-	virtual bool		addActor(TkActor& actor) = 0;
+	virtual bool			addActor(TkActor& actor) = 0;
 
 	/**
 	The number of actors currently in this group.
 
 	\return the number of TkActors that currently exist in this group.
 	*/
-	virtual uint32_t	getActorCount() const = 0;
+	virtual uint32_t		getActorCount() const = 0;
 
 	/**
 	Retrieve an array of pointers (into the user-supplied buffer) to actors.
@@ -90,32 +126,57 @@ public:
 
 	\return the number of TkActor pointers written to the buffer.
 	*/
-	virtual uint32_t	getActors(TkActor** buffer, uint32_t bufferSize, uint32_t indexStart = 0) const = 0;
+	virtual uint32_t		getActors(TkActor** buffer, uint32_t bufferSize, uint32_t indexStart = 0) const = 0;
 
 	/**
-	TkActors that have been damaged with applyFracture() such that they may be split into separate
-	actors are split by this function. TkActors that have damage queued through the actor's damage() function
-	will be fractured and split by this function.
-	Fracture and splitting work will be run on different threads provided through TkGroupDesc::pxTaskManager.  
-	All work is done asynchronously, and the results are gathered by the sync() function.
+	Lock this group for processing concurrently with TkGroupWorker.  The group is unlocked again with the endProcess() function.
 
-	Note: The number of threads provided by pxTaskManager must not change over the group's lifetime.
-
-	\return true if processing may be launched (this group is not currently processing), false otherwise.
+	\return The number of jobs to process. TkGroupWorker::process must be called once for each jobID from 0 to this number-1.
+			See TkGroup::process for a single threaded example.
 	*/
-	virtual bool		process() = 0;
+	virtual uint32_t		startProcess() = 0;
 
 	/**
-	If all threads spawned by process() have finished, and sync() has not yet been called since, then this
-	function gathers the results of the split operations on the actors in this group.  Events will be dispatched
+	Unlock this group after all jobs were processed with TkGroupWorker.  All workers must have been returned with returnWorker().
+	This function gathers the results of the split operations on the actors in this group.  Events will be dispatched
 	to notify listeners of new and deleted actors.
 
-	\param[in]	block	If true, this function waits until all threads have completed execution, then performs the gather and dispatch work.
-						If false, this function will perform the gather and dispatch work only if threads have completed execution, otherwise it returns immediately.
+	Note that groups concurrently dispatching events for the same TkFamily require synchronization in the TkFamily's Listener.
+	However, concurrent use of endProcess is not recommended in this version. It should be called from the main thread.
 
-	\return true if gather and dispatch work have been performed, false otherwise.
+	\return		true	if the group was processing
 	*/
-	virtual bool		sync(bool block = true) = 0;
+	virtual bool			endProcess() = 0;
+
+	/**
+	Set the expected number of concurrent worker threads that will process this group concurrently.
+	*/
+	virtual void			setWorkerCount(uint32_t workerCount) = 0;
+
+	/**
+	\return The total amount of workers allocated for this group.
+	*/
+	virtual uint32_t		getWorkerCount() const = 0;
+
+	/**
+	Acquire one worker to process the group concurrently on a thread.
+	The worker must be returned with returnWorker() before endProcess() is called on its group.
+
+	\return A worker for this group (at most getWorkerCount) or nullptr if none is available.
+	*/
+	virtual TkGroupWorker*	acquireWorker() = 0;
+
+	/**
+	Return a worker previously acquired with acquireWorker() to this TkGroup.
+
+	\param[in] The TkGroupWorker previously acquired from this TkGroup.
+	*/
+	virtual void			returnWorker(TkGroupWorker*) = 0;
+
+	/**
+	Helper function to process the group synchronously on a single thread.
+	*/
+	virtual void			process();
 
 	/**
 	For profile builds only, request stats of the last successful processing. Inactive in other builds.
@@ -123,11 +184,27 @@ public:
 
 	\param[in]	stats	The struct to be filled in.
 	*/
-	virtual void		getStats(TkGroupStats& stats) const = 0;
+	virtual void			getStats(TkGroupStats& stats) const = 0;
 };
 
 } // namespace Blast
 } // namespace Nv
 
 
+NV_INLINE void Nv::Blast::TkGroup::process()
+{
+	uint32_t jobCount = startProcess();
+	if (jobCount > 0)
+	{
+		TkGroupWorker* worker = acquireWorker();
+		for (uint32_t i = 0; i < jobCount; i++)
+		{
+			worker->process(i);
+		}
+		returnWorker(worker);
+	}
+	endProcess();
+}
+
+
 #endif // ifndef NVBLASTTKGROUP_H