// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//  * Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//  * Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//  * Neither the name of NVIDIA CORPORATION nor the names of its
//    contributors may be used to endorse or promote products derived
//    from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Copyright (c) 2008-2023 NVIDIA Corporation. All rights reserved.
// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.  

#ifndef PX_SCENE_QUERY_DESC_H
#define PX_SCENE_QUERY_DESC_H
/** \addtogroup physics
@{
*/

#include "PxPhysXConfig.h"
#include "geometry/PxBVHBuildStrategy.h"

#if !PX_DOXYGEN
namespace physx
{
#endif

	class PxSceneQuerySystem;

/**
\brief Pruning structure used to accelerate scene queries.

eNONE uses a simple data structure that consumes less memory than the alternatives,
but generally has slower query performance.

eDYNAMIC_AABB_TREE usually provides the fastest queries. However there is a
constant per-frame management cost associated with this structure. How much work should
be done per frame can be tuned via the #PxSceneQueryDesc::dynamicTreeRebuildRateHint
parameter.

eSTATIC_AABB_TREE is typically used for static objects. It is the same as the
dynamic AABB tree, without the per-frame overhead. This can be a good choice for static
objects, if no static objects are added, moved or removed after the scene has been
created. If there is no such guarantee (e.g. when streaming parts of the world in and out),
then the dynamic version is a better choice even for static objects.
*/
struct PxPruningStructureType
{
	enum Enum
	{
		eNONE,					//!< Using a simple data structure
		eDYNAMIC_AABB_TREE,		//!< Using a dynamic AABB tree
		eSTATIC_AABB_TREE,		//!< Using a static AABB tree

		eLAST
	};
};

/**
\brief Secondary pruning structure used for newly added objects in dynamic trees.

Dynamic trees (PxPruningStructureType::eDYNAMIC_AABB_TREE) are slowly rebuilt
over several frames. A secondary pruning structure holds and manages objects
added to the scene while this rebuild is in progress.

eNONE ignores newly added objects. This means that for a number of frames (roughly
defined by PxSceneQueryDesc::dynamicTreeRebuildRateHint) newly added objects will
be ignored by scene queries. This can be acceptable when streaming large worlds, e.g.
when the objects added at the boundaries of the game world don't immediately need to be
visible from scene queries (it would be equivalent to streaming that data in a few frames
later). The advantage of this approach is that there is no CPU cost associated with
inserting the new objects in the scene query data structures, and no extra runtime cost
when performing queries.

eBUCKET uses a structure similar to PxPruningStructureType::eNONE. Insertion is fast but
query cost can be high.

eINCREMENTAL uses an incremental AABB-tree, with no direct PxPruningStructureType equivalent.
Query time is fast but insertion cost can be high.

eBVH uses a PxBVH structure. This usually offers the best overall performance.
*/
struct PxDynamicTreeSecondaryPruner
{
	enum Enum
	{
		eNONE,			//!< no secondary pruner, new objects aren't visible to SQ for a few frames
		eBUCKET	,		//!< bucket-based secondary pruner, faster updates, slower query time
		eINCREMENTAL,	//!< incremental-BVH secondary pruner, faster query time, slower updates
		eBVH,			//!< PxBVH-based secondary pruner, good overall performance

		eLAST
	};
};

/**
\brief Scene query update mode

This enum controls what work is done when the scene query system is updated. The updates traditionally happen when PxScene::fetchResults
is called. This function then calls PxSceneQuerySystem::finalizeUpdates, where the update mode is used.

fetchResults/finalizeUpdates will sync changed bounds during simulation and update the scene query bounds in pruners, this work is mandatory.

eBUILD_ENABLED_COMMIT_ENABLED does allow to execute the new AABB tree build step during fetchResults/finalizeUpdates, additionally
the pruner commit is called where any changes are applied. During commit PhysX refits the dynamic scene query tree and if a new tree
was built and the build finished the tree is swapped with current AABB tree. 

eBUILD_ENABLED_COMMIT_DISABLED does allow to execute the new AABB tree build step during fetchResults/finalizeUpdates. Pruner commit
is not called, this means that refit will then occur during the first scene query following fetchResults/finalizeUpdates, or may be forced
by the method PxScene::flushQueryUpdates() / PxSceneQuerySystemBase::flushUpdates().

eBUILD_DISABLED_COMMIT_DISABLED no further scene query work is executed. The scene queries update needs to be called manually, see
PxScene::sceneQueriesUpdate (see that function's doc for the equivalent PxSceneQuerySystem sequence). It is recommended to call
PxScene::sceneQueriesUpdate right after fetchResults/finalizeUpdates as the pruning structures are not updated.
*/
struct PxSceneQueryUpdateMode
{
	enum Enum
	{
		eBUILD_ENABLED_COMMIT_ENABLED,		//!< Both scene query build and commit are executed.
		eBUILD_ENABLED_COMMIT_DISABLED,		//!< Scene query build only is executed.
		eBUILD_DISABLED_COMMIT_DISABLED		//!< No work is done, no update of scene queries
	};
};

/**
\brief Descriptor class for scene query system. See #PxSceneQuerySystem.
*/
class PxSceneQueryDesc
{
public:

	/**
	\brief Defines the structure used to store static objects (PxRigidStatic actors).

	There are usually a lot more static actors than dynamic actors in a scene, so they are stored
	in a separate structure. The idea is that when dynamic actors move each frame, the static structure
	remains untouched and does not need updating.

	<b>Default:</b> PxPruningStructureType::eDYNAMIC_AABB_TREE

	\note Only PxPruningStructureType::eSTATIC_AABB_TREE and PxPruningStructureType::eDYNAMIC_AABB_TREE are allowed here.

	@see PxPruningStructureType PxSceneSQSystem.getStaticStructure()
	*/
	PxPruningStructureType::Enum	staticStructure;

	/**
	\brief Defines the structure used to store dynamic objects (non-PxRigidStatic actors).

	<b>Default:</b> PxPruningStructureType::eDYNAMIC_AABB_TREE

	@see PxPruningStructureType PxSceneSQSystem.getDynamicStructure()
	*/
	PxPruningStructureType::Enum	dynamicStructure;

	/**
	\brief Hint for how much work should be done per simulation frame to rebuild the pruning structures.

	This parameter gives a hint on the distribution of the workload for rebuilding the dynamic AABB tree
	pruning structure #PxPruningStructureType::eDYNAMIC_AABB_TREE. It specifies the desired number of simulation frames
	the rebuild process should take. Higher values will decrease the workload per frame but the pruning
	structure will get more and more outdated the longer the rebuild takes (which can make
	scene queries less efficient).

	\note Only used for #PxPruningStructureType::eDYNAMIC_AABB_TREE pruning structures.

	\note Both staticStructure & dynamicStructure can use a PxPruningStructureType::eDYNAMIC_AABB_TREE, in which case
	this parameter is used for both.

	\note This parameter gives only a hint. The rebuild process might still take more or less time depending on the
	number of objects involved.

	<b>Range:</b> [4, PX_MAX_U32)<br>
	<b>Default:</b> 100

	@see PxSceneQuerySystemBase.setDynamicTreeRebuildRateHint() PxSceneQuerySystemBase.getDynamicTreeRebuildRateHint()
	*/
	PxU32	dynamicTreeRebuildRateHint;

	/**
	\brief Secondary pruner for dynamic tree.

	This is used for PxPruningStructureType::eDYNAMIC_AABB_TREE structures, to control how objects added to the system
	at runtime are managed.

	\note Both staticStructure & dynamicStructure can use a PxPruningStructureType::eDYNAMIC_AABB_TREE, in which case
	this parameter is used for both.

	<b>Default:</b> PxDynamicTreeSecondaryPruner::eINCREMENTAL

	@see PxDynamicTreeSecondaryPruner
	*/
	PxDynamicTreeSecondaryPruner::Enum dynamicTreeSecondaryPruner;

	/**
	\brief Build strategy for PxSceneQueryDesc::staticStructure.

	This parameter is used to refine / control the build strategy of PxSceneQueryDesc::staticStructure. This is only
	used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

	<b>Default:</b> PxBVHBuildStrategy::eFAST

	@see PxBVHBuildStrategy PxSceneQueryDesc::staticStructure
	*/
	PxBVHBuildStrategy::Enum	staticBVHBuildStrategy;

	/**
	\brief Build strategy for PxSceneQueryDesc::dynamicStructure.

	This parameter is used to refine / control the build strategy of PxSceneQueryDesc::dynamicStructure. This is only
	used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

	<b>Default:</b> PxBVHBuildStrategy::eFAST

	@see PxBVHBuildStrategy PxSceneQueryDesc::dynamicStructure
	*/
	PxBVHBuildStrategy::Enum	dynamicBVHBuildStrategy;

	/**
	\brief Number of objects per node for PxSceneQueryDesc::staticStructure.

	This parameter is used to refine / control the number of objects per node for PxSceneQueryDesc::staticStructure.
	This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

	This parameter has an impact on how quickly the structure gets built, and on the per-frame cost of maintaining
	the structure. Increasing this value gives smaller AABB-trees that use less memory, are faster to build and
	update, but it can lead to slower queries.

	<b>Default:</b> 4

	@see PxSceneQueryDesc::staticStructure
	*/
	PxU32	staticNbObjectsPerNode;

	/**
	\brief Number of objects per node for PxSceneQueryDesc::dynamicStructure.

	This parameter is used to refine / control the number of objects per node for PxSceneQueryDesc::dynamicStructure.
	This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

	This parameter has an impact on how quickly the structure gets built, and on the per-frame cost of maintaining
	the structure. Increasing this value gives smaller AABB-trees that use less memory, are faster to build and
	update, but it can lead to slower queries.

	<b>Default:</b> 4

	@see PxSceneQueryDesc::dynamicStructure
	*/
	PxU32	dynamicNbObjectsPerNode;

	/**
	\brief Defines the scene query update mode.

	<b>Default:</b> PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED

	@see PxSceneQuerySystemBase.setUpdateMode() PxSceneQuerySystemBase.getUpdateMode()
	*/
	PxSceneQueryUpdateMode::Enum sceneQueryUpdateMode;

public:
	/**
	\brief constructor sets to default.
	*/	
	PX_INLINE PxSceneQueryDesc();

	/**
	\brief (re)sets the structure to the default.
	*/
	PX_INLINE void setToDefault();

	/**
	\brief Returns true if the descriptor is valid.
	\return true if the current settings are valid.
	*/
	PX_INLINE bool isValid() const;
};

PX_INLINE PxSceneQueryDesc::PxSceneQueryDesc():
	staticStructure				(PxPruningStructureType::eDYNAMIC_AABB_TREE),
	dynamicStructure			(PxPruningStructureType::eDYNAMIC_AABB_TREE),
	dynamicTreeRebuildRateHint	(100),
	dynamicTreeSecondaryPruner	(PxDynamicTreeSecondaryPruner::eINCREMENTAL),
	staticBVHBuildStrategy		(PxBVHBuildStrategy::eFAST),
	dynamicBVHBuildStrategy		(PxBVHBuildStrategy::eFAST),
	staticNbObjectsPerNode		(4),
	dynamicNbObjectsPerNode		(4),
	sceneQueryUpdateMode		(PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED)
{
}

PX_INLINE void PxSceneQueryDesc::setToDefault()
{
	*this = PxSceneQueryDesc();
}

PX_INLINE bool PxSceneQueryDesc::isValid() const
{
	if(staticStructure!=PxPruningStructureType::eSTATIC_AABB_TREE && staticStructure!=PxPruningStructureType::eDYNAMIC_AABB_TREE)
		return false;

	if(dynamicTreeRebuildRateHint < 4)
		return false;

	return true;
}

#if !PX_DOXYGEN
} // namespace physx
#endif

/** @} */
#endif