Updating to [email protected] and [email protected] with a new directory structure.

NvBlast folder is gone, files have been moved to top level directory.  README is changed to reflect this.

1 files changed, 365 insertions, 0 deletions

diff --git a/sdk/toolkit/include/NvBlastTkFramework.h b/sdk/toolkit/include/NvBlastTkFramework.h
new file mode 100644
index 0000000..353eebd
--- /dev/null
+++ b/sdk/toolkit/include/NvBlastTkFramework.h
@@ -0,0 +1,365 @@
+/*
+* 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.
+*/
+
+#ifndef NVBLASTTKFRAMEWORK_H
+#define NVBLASTTKFRAMEWORK_H
+
+
+#include "NvBlastTkType.h"
+#include "NvBlastTkEvent.h"
+
+#include "NvBlastPreprocessor.h"
+#include "NvBlastTypes.h"
+
+#include "PxVec3.h"
+
+
+// Forward declarations
+namespace physx
+{
+class PxErrorCallback;
+class PxAllocatorCallback;
+class PxTransform;
+namespace general_PxIOStream2
+{
+class PxFileBuf;
+}
+}
+
+
+namespace Nv
+{
+namespace Blast
+{
+
+// Forward declarations
+class TkObject;
+class TkEventDispatcher;
+class TkAsset;
+struct TkGroupDesc;
+class TkGroup;
+class TkActor;
+class TkJoint;
+class TkSerializable;
+class TkIdentifiable;
+struct TkAssetJointDesc;
+
+
+
+/**
+Descriptor for framework creation.
+
+The TkFramework uses PxShared callbacks for messages and allocation.
+*/
+struct TkFrameworkDesc
+{
+	physx::PxErrorCallback*		errorCallback;		//!< User-defined message callback (see PxErrorCallback)
+	physx::PxAllocatorCallback*	allocatorCallback;	//!< User-defined allocation callback (see PxAllocatorCallback)
+};
+
+
+/**
+Descriptor for asset creation
+
+Used to create a TkAsset.  This may be used by an authoring tool to describe the asset to be created.
+
+The TkAssetDesc is a simple extension of the low-level NvBlastAsset descriptor, NvBlastAssetDesc.
+*/
+struct TkAssetDesc : public NvBlastAssetDesc
+{
+	/**
+	Flags which may be associated with each bond described in the base NvBlastAssetDesc.
+	*/
+	enum BondFlags
+	{
+		NoFlags = 0,
+
+		/**
+		If this flag is set then a TkJoint will be created joining the support chunks jointed by the bond.
+
+		These joints will remain "quiet" until the actor is split in such a way that the joint joins two
+		different actors.  In that case, a TkJointUpdateEvent will be dispatched with subtype External.
+		(See TkJointUpdateEvent.)
+		*/
+		BondJointed = (1 << 0)
+	};
+
+	/**
+	An array of size bondCount, see BondFlags.
+	If NULL, all flags are assumed to be NoFlags.
+	*/
+	const uint8_t*	bondFlags;
+
+	/** Constructor sets sane default values.  The zero chunkCount will cause TkFramework::createAsset(...) to fail, though gracefully. */
+	TkAssetDesc() : bondFlags(nullptr)
+	{
+		chunkCount = bondCount = 0;
+		chunkDescs = nullptr;
+		bondDescs = nullptr;
+	}
+};
+
+
+/**
+Descriptor for actor creation.
+
+The TkActorDesc is a simple extension of the low-level NvBlastActor descriptor, NvBlastActorDesc.
+*/
+struct TkActorDesc : public NvBlastActorDesc
+{
+	const TkAsset* asset;	//!< The TkAsset to instance
+
+	/** Constructor sets sane default values */
+	TkActorDesc(const TkAsset* inAsset = nullptr) : asset(inAsset)
+	{
+		uniformInitialBondHealth = uniformInitialLowerSupportChunkHealth = 1.0f;
+		initialBondHealths = initialSupportChunkHealths = nullptr;
+	}
+};
+
+
+/**
+Descriptor for joint creation.
+*/
+struct TkJointDesc
+{
+	TkFamily*		families[2];		//!< The TkFamily objects containint the chunks joined by the joint
+	uint32_t		chunkIndices[2];	//!< The chunk indices within the corresponding TkFamily objects joined by the joint.  The indexed chunks will be support chunks.
+	physx::PxVec3	attachPositions[2];	//!< The position of the joint relative to each TkActor which ownes the chunks jointed by this joint
+};
+
+
+/**
+Struct-enum to index object types handled by the framework
+*/
+struct TkTypeIndex
+{
+	enum Enum
+	{
+		Asset = 0,	//!< TkAsset object type
+		Family,		//!< TkFamily object type
+		Group,		//!< TkGroup object type
+
+		TypeCount
+	};
+};
+
+
+/**
+BlastTk Framework.
+
+The framework exists as a singleton and is used to create objects, deserialize object streams, and hold references
+to identified objects (TkAsset, TkFamily, and TkGroup) which may be recalled by their GUIDs.
+*/
+class TkFramework
+{
+public:
+	/**
+	Release this framework and all contained objects.
+	Global singleton is set to NULL.
+	*/
+	virtual void						release() = 0;
+
+	/**
+	Access to the error callback set by the user.
+	*/
+	virtual physx::PxErrorCallback&		getErrorCallback() const = 0;
+
+	/**
+	Access to the allocator callback set by the user.
+	*/
+	virtual physx::PxAllocatorCallback&	getAllocatorCallback() const = 0;
+
+	/**
+	Access to a log function which can be used in Blast low-level calls.
+	This function uses the user-supplied PxErrorCallback (see TkFrameworkDesc).
+	*/
+	virtual NvBlastLog					getLogFn() const = 0;
+
+	/**
+	Deserialize an object from the given stream.  Only objects derived from TkSerializable may be serialized and
+	deserialized.  Use the parent class method TkIdentifiable::getType() to know the type to which to cast the object.
+
+	Notes for different classes:
+
+	TkAsset: deserializing a serialized TkAsset will recreate the asset in memory with the same NvBlastID (see
+	TkIdentifiable::getID()) as the original asset.
+
+	TkFamily: deserializing a serialized TkFamily will generate all TkActor and TkJoint objects that were originally
+	contained in the family.  The TkAsset which generated the family must exist at the time the family is deserialized.
+
+	\param[in]	stream	User-defined stream object.
+
+	\return pointer the deserialized object if successful, or NULL if unsuccessful.
+	*/
+	virtual TkSerializable*				deserialize(physx::general_PxIOStream2::PxFileBuf& stream) = 0;
+
+	/**
+	To find the type information for a given TkIdentifiable-derived class, use this funtion with the TkTypeIndex::Enum
+	corresponding to the desired class name.
+
+	\param[in]	typeIndex	Enumerated object type (see TkTypeIndex).
+
+	\return type object associated with the object's class.
+	*/
+	virtual const TkType*				getType(TkTypeIndex::Enum typeIndex) const = 0;
+
+	/**
+	Look up an object derived from TkIdentifiable by its ID.
+
+	\param[in]	id	The ID of the object to look up (see NvBlastID).
+
+	\return pointer the object if it exists, NULL otherwise.
+	*/
+	virtual TkIdentifiable*				findObjectByID(const NvBlastID& id) const = 0;
+
+	/**
+	The number of TkIdentifiable-derived objects in the framework of the given type.
+
+	\param[in]	type	The type object for the given type.
+
+	\return the number of objects that currently exist of the given type.
+	*/
+	virtual uint32_t					getObjectCount(const TkType& type) const = 0;
+
+	/**
+	Retrieve an array of pointers (into the user-supplied buffer) to TkIdentifiable-derived objects of the given type.
+
+	\param[out]	buffer		A user-supplied array of TkIdentifiable pointers.
+	\param[in]	bufferSize	The number of elements available to write into buffer.
+	\param[in]	type		The type object for the given type.
+	\param[in]	indexStart	The starting index of the object.
+
+	\return the number of TkIdentifiable pointers written to the buffer.
+	*/
+	virtual uint32_t					getObjects(TkIdentifiable** buffer, uint32_t bufferSize, const TkType& type, uint32_t indexStart = 0) const = 0;
+
+	//////// Asset creation ////////
+	/**
+	Helper function to build and apply chunk reorder map, so that chunk descriptors are properly ordered for the createAsset function.
+
+	This is a convenience wrapper for the low-level NvBlastReorderAssetDescChunks function.
+
+	This function may modify both the chunkDescs and bondDescs array, since rearranging chunk descriptors requires re-indexing within the bond descriptors.
+
+	\param[in]  chunkDescs		Array of chunk descriptors of size chunkCount. It will be updated accordingly.
+	\param[in]  chunkCount		The number of chunk descriptors.
+	\param[in]  bondDescs		Array of bond descriptors of size chunkCount. It will be updated accordingly.
+	\param[in]  bondCount		The number of bond descriptors.
+	\param[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.
+
+	\return	true iff the chunks did not require reordering (chunkReorderMap is the identity map).
+	*/
+	virtual bool						reorderAssetDescChunks(NvBlastChunkDesc* chunkDescs, uint32_t chunkCount, NvBlastBondDesc* bondDescs, uint32_t bondCount, uint32_t* chunkReorderMap = nullptr) const = 0;
+
+	/**
+	Helper function to ensure (check and update) support coverage of chunks, required for asset creation via the createAsset function.
+
+	This is a convenience wrapper for the low-level NvBlastEnsureAssetExactSupportCoverage function.
+
+	The chunk descriptors may have their support flags be modified to ensure exact coverage.
+
+	\param[in]	chunkDescs	An array of chunk descriptors.
+	\param[in]	chunkCount	The size of the chunkDescs array.
+
+	\return	true iff coverage was already exact.
+	*/
+	virtual bool						ensureAssetExactSupportCoverage(NvBlastChunkDesc* chunkDescs, uint32_t chunkCount) const = 0;
+
+	/**
+	Create an asset from the given descriptor.
+
+	\param[in]	desc	The asset descriptor (see TkAssetDesc).
+
+	\return the created asset, if the descriptor was valid and memory was available for the operation.  Otherwise, returns NULL.
+	*/
+	virtual TkAsset*					createAsset(const TkAssetDesc& desc) = 0;
+
+	/**
+	Create an asset from a low-level NvBlastAsset.
+
+	\param[in]	assetLL			The low-level NvBlastAsset to encapsulate.
+	\param[in]	jointDescs		Optional joint descriptors to add to the new asset.
+	\param[in]	jointDescCount	The number of joint descriptors in the jointDescs array.  If non-zero, jointDescs cannot be NULL.
+	\param[in]  ownsAsset		Does this TkAsset own the NvBlastAsset and thus is responsible for freeing it.
+
+	\return the created asset, if memory was available for the operation.  Otherwise, returns NULL.
+	*/
+	virtual TkAsset*					createAsset(const NvBlastAsset* assetLL, Nv::Blast::TkAssetJointDesc* jointDescs = nullptr, uint32_t jointDescCount = 0, bool ownsAsset = false) = 0;
+
+	//////// Group creation ////////
+	/**
+	Create a group from the given descriptor.  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 optionally
+	placed into another group, or left groupless.
+
+	\param[in]	desc	The group descriptor (see TkGroupDesc).
+
+	\return the created group, if the descriptor was valid and memory was available for the operation.  Otherwise, returns NULL.
+	*/
+	virtual TkGroup*					createGroup(const TkGroupDesc& desc) = 0;
+
+	//////// Actor creation ////////
+	/**
+	Create an actor from the given descriptor.  The actor will be the first member of a new TkFamily.
+
+	\param[in]	desc	The actor descriptor (see TkActorDesc).
+
+	\return the created actor, if the descriptor was valid and memory was available for the operation.  Otherwise, returns NULL.
+	*/
+	virtual TkActor*					createActor(const TkActorDesc& desc) = 0;
+
+	//////// Joint creation ////////
+	/**
+	Create a joint from the given descriptor.  The following restrictions apply:
+	
+	* Only one joint may be created between any two support chunks.
+
+	* A joint cannot be created between chunks within the same actor using this method.  See TkAssetDesc for a description of
+	bond joint flags, which will create internal joints within an actor.
+
+	\param[in]	desc	The joint descriptor (see TkJointDesc).
+
+	\return the created joint, if the descriptor was valid and memory was available for the operation.  Otherwise, returns NULL.
+	*/
+	virtual TkJoint*					createJoint(const TkJointDesc& desc)  = 0;
+
+protected:
+	/**
+	Destructor is virtual and not public - use the release() method instead of explicitly deleting the TkFramework
+	*/
+	virtual								~TkFramework() {}
+};
+
+} // namespace Blast
+} // namespace Nv
+
+
+//////// Global API to Create and Access Framework ////////
+
+/**
+Create a new TkFramework.  This creates a global singleton, and will fail if a TkFramework object already exists.
+
+\param[in]	desc	The descriptor used to create the new framework (see TkFrameworkDesc).
+
+\return the new TkFramework if successful, NULL otherwise.
+*/
+NVBLAST_API Nv::Blast::TkFramework* NvBlastTkFrameworkCreate(const Nv::Blast::TkFrameworkDesc& desc);
+
+
+/**
+Retrieve a pointer to the global TkFramework singleton (if it exists).
+
+\return the pointer to the global TkFramework (NULL if none exists).
+*/
+NVBLAST_API Nv::Blast::TkFramework* NvBlastTkFrameworkGet();
+
+
+#endif // ifndef NVBLASTTKFRAMEWORK_H