source: GTP/trunk/App/Games/Jungle_Rumble/src/physic/physics/include/NxScene.h @ 1378

#ifndef NX_PHYSICS_NX_SCENE
#define NX_PHYSICS_NX_SCENE
/*----------------------------------------------------------------------------*\
|
|                                               Public Interface to NovodeX Technology
|
|                                                            www.novodex.com
|
\*----------------------------------------------------------------------------*/
/** \addtogroup physics
  @{
*/

#include "Nxp.h"
#include "NxUserRaycastReport.h"
#include "NxUserEntityReport.h"
#include "NxSceneDesc.h"
#include "NxSceneStats.h"
#include "NxArray.h"
#include "NxProfiler.h"
#if NX_USE_FLUID_API
#include "fluids/NxFluid.h"
class NxUserFluidContactReport;
#endif

class NxActor;
class NxActorDescBase;
class NxJoint;
class NxJointDesc;
class NxEffector;
class NxShape;
class NxUserNotify;
class NxUserTriggerReport;
class NxUserContactReport;
class NxSpringAndDamperEffector;
class NxSpringAndDamperEffectorDesc;
class NxRay;
class NxBounds3;
class NxPlane;
class NxSphere;
class NxCapsule;
class NxThread;
class NxTriangle;
class NxPhysicsSDK;
class NxMaterialDesc;
class NxMaterial;
class NxDebugRenderable;

/**
\brief Struct used by NxScene::getPairFlagArray().

The high bit of each 32 bit     flag field denotes whether a pair is a shape or an actor pair.
The flags are defined by the enum NxContactPairFlag.

@see NxScene.getPairFlagArray
*/
class NxPairFlag
        {
        public:
        void*   objects[2];
        NxU32   flags;

        NX_INLINE NxU32 isActorPair() const { return flags & 0x80000000;        }
        };


/**
\brief Enum describing syncronization conditions.
*/
enum NxStandardFences
        {
        NX_FENCE_RUN_FINISHED,
        /*NX_SYNC_RAYCAST_FINISHED,*/
        NX_NUM_STANDARD_FENCES,
        };

/**
 enum to check if a certain part of the SDK has finished.
 used in:
 bool checkResults(NxSimulationStatus, bool block = false)
 bool fetchResults(NxSimulationStatus, bool block = false)

 @see NxScene.checkResults() NxScene.fetchResults()
*/
enum NxSimulationStatus
        {
        NX_RIGID_BODY_FINISHED  = (1<<0),
        };

/** 
 \brief A scene is a collection of bodies, constraints, and effectors which can interact.

 The scene simulates the behavior of these objects over time. Several scenes may exist 
 at the same time, but each body, constraint, or effector object is specific to a scene 
 -- they may not be shared.

 For example, attempting to create a joint in one scene and then using it to attach
 bodies from a different scene results in undefined behavior.

 <h3>Creation</h3>

 Example:

 \include NxScene_Create.cpp

 @see NxSceneDesc NxPhysicsSDK.createScene() NxPhysicsSDK.releaseScene()
*/
class NxScene
        {
        protected:
                                                                                NxScene()       {}
        virtual                                                         ~NxScene()      {}

        public:


        /**
        \brief Saves the Scene descriptor.

        \param[out] desc The descriptor used to retrieve the state of the object.
        \return True on success.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSceneDesc
        */
        virtual bool                            saveToDesc(NxSceneDesc& desc)   const   = 0;


        /**
        \brief Gets a private interface to an internal debug object.
        
        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes
        */
        virtual void *                                          getInternal(void) = 0;

        /**
        \brief Sets a constant gravity for the entire scene.

        <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.

        \param[in] vec A new gravity vector(eg NxVec3(0.0f,-9.8f,0.0f) ) <b>Range:</b> force vector

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSceneDesc.gravity getGravity()
        */
        virtual void                                            setGravity(const NxVec3& vec) = 0;

        /**
        \brief Retrieves the current gravity setting.

        \param[out] vec Used to retrieve the current gravity for the scene.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see setGravity() NxSceneDesc.gravity
        */
        virtual void                                            getGravity(NxVec3& vec) = 0;

/************************************************************************************************/

/** @name Create/Release Objects
*/
//@{

        /**
        \brief Creates an actor in this scene.
        
        NxActorDesc::isValid() must return true.

        <b>Sleeping:</b> This call wakes the actors if they are sleeping.

        \param[in] desc Descriptor for actor to create. See #NxActorDescBase
        \return The new actor.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes (Limits on numbers and types of actors)
        \li PS3  : Yes
        \li XB360: Yes

        @see NxActor NxActorDesc NxActorDescBase releaseActor()
        */
        virtual NxActor*                                        createActor(const NxActorDescBase& desc) = 0;

        /**
        \brief Deletes the specified actor.
        
        The actor must be in this scene.
        Do not keep a reference to the deleted instance.

        Note: deleting a static actor will not wake up any sleeping objects that were
        sitting on it. Use a kinematic actor instead to get this behavior.

        <b>Sleeping:</b> This call wakes the actors if they are sleeping.

        \param[in] actor The actor to release.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see createActor() NxActor
        */
        virtual void                                            releaseActor(NxActor& actor) = 0;

        /**
        \brief Creates a joint.
        
        The joint type depends on the type of joint desc passed in.

        <b>Sleeping:</b> This call wakes the actor(s) if they are sleeping.

        \param[in] jointDesc The descriptor for the joint to create. Eg #NxSphericalJointDesc,#NxRevoluteJointDesc etc
        \return The new joint.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxJoint NxJointDesc releaseJoint() NxJoint
        @see NxRevoluteJoint NxSphericalJoint NxPrismaticJoint NxCylindricalJoint NxD6Joint NxDistanceJoint
        NxFixedJoint NxPointInPlaneJoint NxPointOnLineJoint
        */
        virtual NxJoint *                                       createJoint(const NxJointDesc &jointDesc) = 0;

        /**
        \brief Deletes the specified joint.
        
        The joint must be in this scene.
        Do not keep a reference to the deleted instance.

        <b>Sleeping:</b> This call wakes the actor(s) if they are sleeping.

        \param[in] joint The joint to release.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes
        */
        virtual void                                            releaseJoint(NxJoint &joint) = 0;

        /**
        \brief Creates a spring and damper effector.

        <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.

        \param[in] springDesc The descriptor for the spring and damper effector to create. See #NxSpringAndDamperEffectorDesc.
        \return The new spring and damper.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSpringAndDamperEffectorDesc NxSpringAndDamperEffector releaseEffector()
        */
        virtual NxSpringAndDamperEffector*      createSpringAndDamperEffector(const NxSpringAndDamperEffectorDesc& springDesc) = 0;

        /**
        \brief Deletes the effector passed.

        Do not keep a reference to the deleted instance.

        <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.

        \param[in] effector The effector to delete.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see createSpringAndDamperEffector NxSpringAndDamperEffector
        */
        virtual void                                            releaseEffector(NxEffector& effector) = 0;

        /**
        \brief Creates a new NxMaterial.

        The material library consists of an array of material objects. Each
        material has a well defined index that can be used to refer to it.
        If an object (shape or triangle) references an undefined material,
        the default material with index 0 is used instead.

        \param[in] matDesc The material desc to use to create a material. See #NxMaterialDesc.
        \return The new material.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see NxMaterial NxMaterialDesc releaseMaterial()
        */
        virtual NxMaterial *                            createMaterial(const NxMaterialDesc &matDesc) = 0;

        /**
        \brief Deletes the specified material.
        
        The material must be in this scene.
        Don not keep a reference to the deleted instance.
        If you release a material while shapes or meshes are referencing its material index,
        the material assignment of these objects becomes undefined.

        \param[in] material The material to release.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see createMaterial() NxMaterial
        */
        virtual void                                            releaseMaterial(NxMaterial &material) = 0;
//@}
/************************************************************************************************/

/** @name Collision Filtering and Grouping
*/
//@{

        /**
        \brief Sets the pair flags for the given pair of actors.

        The pair flags are a combination of bits
        defined by ::NxContactPairFlag. Calling this on an actor that has no shape(s) has no effect.
        The two actor references must not reference the same actor.

        It is important to note that the SDK stores pair flags per shape, even for actor pair flags. 
        This means that shapes should be created before actor pair flags are set, otherwise the pair
        flags will be ignored.

        <b>Sleeping:</b> Does <b>NOT</b> wake the actors up automatically.

        \param[in] actorA Actor A
        \param[in] actorB Actor B
        \param[in] nxContactPairFlag New set of contact pair flags. See #NxContactPairFlag

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see getActorPairFlags() NxContactPairFlag
        */
        virtual void                                            setActorPairFlags(NxActor& actorA, NxActor& actorB, NxU32 nxContactPairFlag) = 0;

        /**
        \brief Retrieves the pair flags for the given pair of actors.
        
        The pair flags are a combination of bits
        defined by ::NxContactPairFlag. If no pair record is found, zero is returned.
        The two actor references must not reference the same actor.

        \param[in] actorA Actor A
        \param[in] actorB Actor B
        \return The actor pair flags.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes
        
        @see setActorPairFlags() NxContactPairFlag
        */
        virtual NxU32                                           getActorPairFlags(NxActor& actorA, NxActor& actorB) const = 0;

        /**
        \brief Similar to #setActorPairFlags(), but for a pair of shapes.
        
        NX_IGNORE_PAIR is the only thing allowed
        as a shape pair flag.  All of the NX_NOTIFY flags should be used at the actor level.
        The two shape references must not reference the same shape.

        <b>Sleeping:</b> Does <b>NOT</b> wake the associated actors up automatically.

        \param[in] shapeA Shape A
        \param[in] shapeB Shape B
        \param[in] nxContactPairFlag New set of shape contact pair flags.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see getShapePairFlags() NxContactPairFlag
        */
        virtual void                                            setShapePairFlags(NxShape& shapeA, NxShape& shapeB, NxU32 nxContactPairFlag) = 0;

        /**
        \brief Similar to getPairFlags(), but for a pair of shapes.

        The two shape references must not reference the same shape.

        \param[in] shapeA Shape A
        \param[in] shapeB SHape B
        \return The shape pair flags.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setShapePairFlags() NxContactPairFlag
        */
        virtual NxU32                                           getShapePairFlags(NxShape& shapeA, NxShape& shapeB) const = 0;

        /**
        \brief Returns the number of pairs for which pairFlags are defined. 
        
        This includes actor and shape pairs.

        \return The number of pairs.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxContactPairFlag setShapePairFlags() setActorPairFlags() getPairFlagArray()
        */
        virtual NxU32                                           getNbPairs() const = 0;

        /**
        \brief Retrieves the pair data.
        
        The high bit of each 32 bit flag field denotes whether a pair is a shape or
        an actor pair. numPairs is the number of pairs the buffer can hold. The user is responsible for
        allocating and deallocating the buffer. Call ::getNbPairs() to check what the number of pairs should be.
        

        \param[out] userArray Pointer to user array to recieve pair flags. should be at least sizeof(NxPairFlag)*numPairs in size.
        \param[in] numPairs Number of pairs the user buffer can hold.
        \return The number of pairs written to userArray.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxContactPairFlag setShapePairFlags() setActorPairFlags() getNbPairs()
        */
        virtual NxU32                                           getPairFlagArray(NxPairFlag* userArray, NxU32 numPairs) const = 0;

        /**
        \brief Specifies if collision should be performed by a pair of shape groups.
        
        It is possible to assign each shape to a collision groups using #NxShape::setGroup().
        With this method one can set whether collisions should be detected between shapes 
        belonging to a given pair of groups. Initially all pairs are enabled.

        Collision detection between two shapes a and b occurs if: 
        getGroupCollisionFlag(a->getGroup(), b->getGroup()) && isEnabledPair(a,b) is true.

        Fluids can be assigned to collision groups as well.

        NxCollisionGroup is an integer between 0 and 31.

        <b>Sleeping:</b> Does <b>NOT</b> wake the associated actors up automatically.

        \param[in] group1 First group.
        \param[in] group2 Second group.
        \param[in] enable True to enable collision between the groups.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxCollisionGroup getGroupCollisionFlag() NxShape.setGroup() NxShape.getGroup()
        */
        virtual void setGroupCollisionFlag(NxCollisionGroup group1, NxCollisionGroup group2, bool enable) = 0;

        /**
        \brief Determines if collision detection is performed between a pair of groups.

        NxCollisionGroup is an integer between 0 and 31.

        \param[in] group1 First Group.
        \param[in] group2 Second Group.
        \return True if the groups could collide.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setGroupCollisionFlag() NxCollisionGroup NxShape.setGroup() NxShape.getGroup()
        */
        virtual bool getGroupCollisionFlag(NxCollisionGroup group1, NxCollisionGroup group2) const = 0;

        /**
        \brief With this method one can set contact reporting flags between actors belonging to a pair of groups.

        It is possible to assign each actor to a group using NxActor::setGroup(). This is a different
        set of groups from the shape groups despite the similar name. Here up to 0xffff different groups are permitted,
        With this method one can set contact reporting flags between actors belonging to a pair of groups.

        The following flags are permitted:

        NX_NOTIFY_ON_START_TOUCH
        NX_NOTIFY_ON_END_TOUCH  
        NX_NOTIFY_ON_TOUCH              
        NX_NOTIFY_ON_IMPACT             
        NX_NOTIFY_ON_ROLL               
        NX_NOTIFY_ON_SLIDE      

        See ::NxContactPairFlag.

        Note that finer grain control of pairwise flags is possible using the functions
        NxScene::setShapePairFlags() and NxScene::setActorPairFlags().

        <b>Sleeping:</b> Does <b>NOT</b> wake the actors up automatically.

        \param[in] group1 First Group.
        \param[in] group2 Second Grooup
        \param[in] flags Flags to control contact reporting. See #NxContactPairFlag.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getActorGroupPairFlags() NxActorGroup NxActor.getGroup() NxActor.setGroup()
        */
        virtual void setActorGroupPairFlags(NxActorGroup group1, NxActorGroup group2, NxU32 flags) = 0;

        /**
        \brief This reads the value set with #setActorGroupPairFlags.

        \param[in] group1 First Group
        \param[in] group2 Second Group
        \return The contact reporting flags associated with this actor pair. See #setActorGroupPairFlags.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see setActorPairFlags() NxActorGroup NxActor.getGroup() NxActor.setGroup()
        */
        virtual NxU32 getActorGroupPairFlags(NxActorGroup group1, NxActorGroup group2) const = 0;

#ifdef NX_SUPPORT_NEW_FILTERING
        /**
        \brief Setups filtering operations. See comments for ::NxGroupsMask

        <b>Sleeping:</b> Does <b>NOT</b> wake the actors up automatically.

        \param[in] op0 Filter op 0.
        \param[in] op1 Filter op 1.
        \param[in] op2 Filter op 2.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setFilterBool() setFilterConstant0() setFilterConstant1()
        */
        virtual void    setFilterOps(NxFilterOp op0, NxFilterOp op1, NxFilterOp op2)    = 0;

        /**
        \brief Setups filtering's boolean value. See comments for ::NxGroupsMask

        <b>Sleeping:</b> Does <b>NOT</b> wake the actors up automatically.

        \param[in] flag Boolean value for filter.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setFilterOps() setFilterConstant0() setFilterConstant1()
        */
        virtual void    setFilterBool(bool flag)                                                                                = 0;

        /**
        \brief Setups filtering's K0 value. See comments for ::NxGroupsMask

        <b>Sleeping:</b> Does <b>NOT</b> wake the actors up automatically.

        \param[in] mask The new group mask. See #NxGroupsMask.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setFilterOps() setFilterBool() setFilterConstant1()
        */
        virtual void    setFilterConstant0(const NxGroupsMask& mask)                                    = 0;

        /**
        \brief Setups filtering's K1 value. See comments for ::NxGroupsMask

        <b>Sleeping:</b> Does <b>NOT</b> wake the actors up automatically.

        \param[in] mask The new group mask. See #NxGroupsMask.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setFilterOps() setFilterBool() setFilterConstant0()
        */
        virtual void    setFilterConstant1(const NxGroupsMask& mask)                                    = 0;
#endif  

//@}
/************************************************************************************************/

/** @name Enumeration
*/
//@{

        /**
        \brief Retrieve the number of actors in the scene.
        \return the number of actors.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getActors()
        */
        virtual NxU32                                           getNbActors()           const   = 0;

        /**
        \brief Retrieve an array of all the actors in the scene.

        \return an array of actor pointers with size getNbActors().

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getNbActors()
        */
        virtual NxActor**                                       getActors()                                     = 0;

        /**
        \brief Returns the number of static shapes in the scene.

        \return the number of static shapes.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getNbDynamicShapes();
        @see getTotalNbShapes()
        */
        virtual NxU32                                           getNbStaticShapes()             const   = 0;

        /**
        \brief Returns the number of dynamic shapes in the scene.

        \return the number of dynamic shapes.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getNbStaticShapes()
        @see getTotalNbShapes()
        */
        virtual NxU32                                           getNbDynamicShapes()    const   = 0;

        /**
        \brief Returns the total number of shapes in the scene, including compounds' sub-shapes.

        \return the total number of shapes.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getNbStaticShapes()
        @see getNbDynamicShapes()
        */
        virtual NxU32                                           getTotalNbShapes()      const   = 0;

        /**
        \brief Returns the number of joints in the scene.

        \return the number of joints in this scene. This includes all joints, even broken ones.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see getNextJoint()
        */
        virtual NxU32                                           getNbJoints()           const   = 0;

        /**

        \brief Restarts the joint iterator so that the next call to ::getNextJoint() returns the first joint in the scene.

        Creating or deleting joints resets the joint iterator.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see resetJointIterator() getNbJoints()
        */
        virtual void                                            resetJointIterator()     = 0;

        /**
        \brief Retrieves the next joint when iterating.
        
        First call resetJointIterator(), then call this method repeatedly until it returns
        zero. After a call to resetJointIterator(), repeated calls to getNextJoint() should return a sequence of getNbJoints()
        joint pointers. The getNbJoints()+1th call will return 0.
        Creating or deleting joints resets the joint iterator.

        @see resetJointIterator.

        \return The next joint in the iteration sequence. Or NULL when the end of the list of joints is reached.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see resetJointIterator() getNbJoints()
        */
        virtual NxJoint *                                       getNextJoint()   = 0;

        /**
        \brief Returns the number of effectors in the scene.

        \return the number of effectors in this scene.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see getNextEffector()
        */
        virtual NxU32                                           getNbEffectors()                const   = 0;

        /**
    \brief Restarts the effector iterator so that the next call to ::getNextEffector() returns the first effector in the scene.
        
        Creating or deleting effectors resets the joint iterator.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see getNextEffector() getNbEffectors()
        */
        virtual void                                            resetEffectorIterator()  = 0;

        /**
        \brief Retrieves the next effector when iterating through the effectors in the scene.
        
        First call resetEffectorIterator(), then call this method repeatedly until it returns
        zero. After a call to resetEffectorIterator(), repeated calls to getNextEffector() should return a sequence of getNbEffectors()
        effector pointers. The getNbEffectors()+1th call will return 0.
        Creating or deleting effectors resets the joint iterator.

        @see resetEffectorIterator.

        \return The next effector in the iteration sequence. Or NULL when the end of the list of joints is reached.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see resetEffectorIterator() getNbEffectors()
        */
        virtual NxEffector *                            getNextEffector() = 0;
//@}
/************************************************************************************************/

/** @name Materials
*/
//@{

        /**
        \brief Return the number of materials in the scene.

        Note that the returned value is not related to material indices (NxMaterialIndex).
        Those may not be allocated continuously, and its values may be higher than getNbMaterials().
        This will also include the default material which exists without having to be created.

        \return The size of the internal material array.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getMaterialArray()
        */
        virtual NxU32                                           getNbMaterials() const = 0;

        /**
        \brief Writes the scene's array of material pointers to a user buffer.
        
        bufferSize is the number of pointers (not bytes) that the buffer can hold.
        usersIterator is an iterator that the user should initialize to 0 to start copying the array from the beginning.
        Once the first call succeeds, the SDK will have changed the value of the iterator (in some data structure specific way) such that the
        next get*Array() call will return the next batch of values.  This way a large internal array can be read out with several calls into 
        a smaller user side buffer.
        
        Returns the number of pointers written, this should be less or equal to bufferSize.  This will also return the default material which exists without having to be created.

        The ordering of the materials in the array is not specified.

        Usage example:
        \code
        NxMaterial * ptrs[3];
        NxU32 iterator = 0;
        while (3 == s->getMaterialArray(ptrs, 3, iterator))
                process3Materials(ptrs);

        \endcode

        \param[out] userBuffer The buffer to recieve material pointers.
        \param[in] bufferSize The number of material pointers which can be stored in the buffer.
        \param[in,out] usersIterator Cookie used to continue iteration from the last position.
        \return The number of material pointers written to userBuffer.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see getNbMaterials() NxMaterial
        */
        virtual NxU32                                           getMaterialArray(NxMaterial ** userBuffer, NxU32 bufferSize, NxU32 & usersIterator) = 0;

        /**
        \brief Returns current highest valid material index.
        
        Note that not all indices below this are valid if some of them belong to meshes that
        have been freed.

        \return The highest material index.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see NxMaterial NxMaterialIndex NxScene.createMaterial()
        */

        virtual NxMaterialIndex                         getHighestMaterialIndex() const = 0;

        /**
        \brief Retrieves the material with the given material index.
        
        If the material index is out of range or belongs to a material that was released, 0 is returned, 
        but no error is reported.
        You can get a pointer to the default material (the material that all invalid material indices are mapped to) by using index 0.
        You can then change this default material.  Releasing the default material has no effect.

        \param[in] matIndex Material index to retrieve.
        \return The associated material.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see NxMaterial NxMaterialIndex NxScene.createMaterial() getHighestMaterialIndex()
        */
        virtual NxMaterial *                            getMaterialFromIndex(NxMaterialIndex matIndex) = 0;

//@}
/************************************************************************************************/

        /**
        \brief Flush the scene's command queue for processing.

        Flushes any buffered commands so that they get executed.
        Ensures that commands buffered in the system will continue to make forward progress until completion.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see setTiming() simulate() fetchResults() checkResults()
        */
        virtual void                                            flushStream() = 0;

        /**
        \brief Sets simulation timing parameters used in simulate(elapsedTime).

        If method is NX_TIMESTEP_FIXED, elapsedTime is internally subdivided into up to
        maxIter substeps no larger than maxTimestep.
        
        If elapsedTime is not a multiple of maxTimestep then any remaining time is accumulated 
        to be added onto the elapsedTime for the next time step.

        If more sub steps than maxIter are needed to advance the simulation by elapsed time, then
        the remaining time is also accumulated for the next call to simulate().
        
        The timestep method of TIMESTEP_FIXED is strongly preferred for stable, reproducible simulation.

        Alternatively NX_TIMESTEP_VARIABLE can be used, in this case the first two parameters
        are not used.   See also ::NxTimeStepMethod.

        \param[in] maxTimestep Maximum size to take for a timestep. <b>Range:</b> (0,inf)
        \param[in] maxIter Maximum number of iterations to divide a timestep into.
        \param[in] method Method to use for for timestepp(either variable time step or fixed). See #NxTimeStepMethod.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see flushStream() simulate() fetchResults() checkResults()
        */
        virtual void                                            setTiming(NxReal maxTimestep=1.0f/60.0f, NxU32 maxIter=8, NxTimeStepMethod method=NX_TIMESTEP_FIXED) = 0;

        /**
        \brief Retrieves simulation timing parameters.

        \param[in] maxTimestep Maximum size to take for a timestep. <b>Range:</b> (0,inf)
        \param[in] maxIter Maximum number of iterations to divide a timestep into.
        \param[in] method Method to use for for timestepp(either variable time step or fixed). See #NxTimeStepMethod.
        \param[in] numSubSteps The number of sub steps the time step will be divided into.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see setTiming()
        */
        virtual void                                            getTiming(NxReal& maxTimestep, NxU32& maxIter, NxTimeStepMethod& method, NxU32* numSubSteps=NULL) const = 0;

        /**
        \brief Retrieves the debug renderable.
        
        This will contain the results of any active visualization for this scene.
        \return The debug renderable.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxDebugRenderable
        */
        virtual const NxDebugRenderable *       getDebugRenderable() = 0;

        /**
        \brief Call this method to retrieve the Physics SDK.

        \return The physics SDK this scene is associated with.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see NxPhysicsSDK
        */
        virtual NxPhysicsSDK&                           getPhysicsSDK() = 0;

        /**
        \brief Call this method to retrieve statistics about the current scene.

        \param[out] stats Used to retrieve statistics for the scene. See #NxSceneStats.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSceneStats getLimits()
        */
        virtual void                                            getStats(NxSceneStats& stats) const = 0;

        /**
        \brief Call to retrieve the expected object count limits set in the scene descriptor.

        \param[out] limits Used to retrieve the limits for the scene(eg maximum number of actors). See #NxSceneLimits.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSceneLimits getStats() NxSceneStats
        */
        virtual void                                            getLimits(NxSceneLimits& limits) const = 0;

/************************************************************************************************/

/** @name Callbacks
*/
//@{

        /**
        \brief Sets a user notify object which receives special simulation events when they occur.

        \param[in] callback User notification callback. See #NxUserNotify.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxUserNotify getUserNotify
        */
        virtual void                                            setUserNotify(NxUserNotify* callback) = 0;

        /**
        \brief Retrieves the userNotify pointer set with setUserNotify().

        \return The current user notify pointer. See #NxUserNotify.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxUserNotify setUserNotify()
        */
        virtual NxUserNotify*                           getUserNotify() const = 0;

        /**
        \brief Sets a trigger report object which receives collision trigger events.

        \param[in] callback User trigger callback. See #NxUserTriggerReport.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxUserTriggerReport getUserTriggerReport()
        */
        virtual void                                            setUserTriggerReport(NxUserTriggerReport* callback) = 0;

        /**
        \brief Retrieves the callback pointer set with setUserTriggerReport().

        \return The current user trigger pointer. See #NxUserTriggerReport.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxUserTriggerReport setUserTriggerReport()
        */
        virtual NxUserTriggerReport*            getUserTriggerReport() const = 0;

        /**
        \brief Sets a contact report object which receives collision contact events.

        \param[in] callback User contact callback. See #NxUserContactReport.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxUserContactReport getUserContactReport()
        */
        virtual void                                            setUserContactReport(NxUserContactReport* callback) = 0;

        /**
        \brief Retrieves the callback pointer set with setUserContactReport().

        \return The current user contact reporter. See #NxUserContactReport.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxUserContactReport setUserContactReport()
        */
        virtual NxUserContactReport*            getUserContactReport() const = 0;

#if NX_USE_FLUID_API

        /**
        Not available in the current release.
        The fluid equivalent for registering a specialized version of the user contact report.

        \param[in] callback User fluid contact callback. See #NxUserFluidContactReport.

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : No
        \li PS3  : No
        \li XB360: No
        */
        virtual void                                            setUserFluidContactReport(NxUserFluidContactReport* callback) = 0;
        
        /**
        Not available in the current release.
        Retrieves the callback pointer set with setUserFluidContactReport().
        
        \return The current user fluid contact reporter. See #NxUserFluidContactReport.
        
        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : No
        \li PS3  : No
        \li XB360: No
        */
        virtual NxUserFluidContactReport*       getUserFluidContactReport() const = 0;

#endif
//@}
/************************************************************************************************/

/** @name Raycasting
*/
//@{

        /**
        \brief Returns true if any axis aligned bounding box enclosing a shape of type shapeType is intersected by the ray.

        Note: Make certain that the direction vector of NxRay is normalized.

        \param[in] worldRay The ray to cast in the global frame. <b>Range:</b> See #NxRay
        \param[in] shapesType Choose if to raycast against static, dynamic or both types of shape. See #NxShapesType.
        \param[in] groups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] maxDist Max distance to check along the ray for intersecting bounds. <b>Range:</b> (0,inf)
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return true if any axis aligned bounding box enclosing a shape of type shapeType is intersected by the ray

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxShapesType NxRay NxShape.setGroup()  raycastAnyShape()
        */
        virtual bool                                            raycastAnyBounds                (const NxRay& worldRay, NxShapesType shapesType, NxU32 groups=0xffffffff, NxReal maxDist=NX_MAX_F32, const NxGroupsMask* groupsMask=NULL) const = 0;

        /**
        \brief Returns true if any shape of type ShapeType is intersected by the ray.

        Note: Make certain that the direction vector of NxRay is normalized.

        \param[in] worldRay The ray to cast in the global frame. <b>Range:</b> See #NxRay
        \param[in] shapesType Choose if to raycast against static, dynamic or both types of shape. See #NxShapesType.
        \param[in] groups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] maxDist Max distance to check along the ray for intersecting objects. <b>Range:</b> (0,inf) 
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return Returns true if any shape of type ShapeType is intersected by the ray.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxShapesType NxRay NxShape.setGroup()  raycastAnyBounds()
        */
        virtual bool                                            raycastAnyShape                 (const NxRay& worldRay, NxShapesType shapesType, NxU32 groups=0xffffffff, NxReal maxDist=NX_MAX_F32, const NxGroupsMask* groupsMask=NULL) const = 0;

        /**
        \brief Calls the report's hitCallback() method for all the axis aligned bounding boxes enclosing shapes of type ShapeType intersected by the ray.
        
        The point of impact is provided as a parameter to hitCallback().
        hintFlags is a combination of ::NxRaycastBit flags.
        Returns the number of shapes hit.

        Note: Make certain that the direction vector of NxRay is normalized.

        \param[in] worldRay The ray to cast in the global frame. <b>Range:</b> See #NxRay
        \param[in] report User callback, to be called when an intersection is encountered.
        \param[in] shapesType Choose if to raycast against static, dynamic or both types of shape. See #NxShapesType.
        \param[in] groups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] maxDist Max distance to check along the ray for intersecting objects. <b>Range:</b> (0,inf) 
        \param[in] hintFlags Allows the user to specify which field of #NxRaycastHit they are interested in.
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return the number of shapes hit.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see raycastAnyBounds() raycastAllShapes() NxRay NxUserRaycastReport NxShapesType NxShape.setGroup() NxRaycastHit
        */
        virtual NxU32                                           raycastAllBounds                (const NxRay& worldRay, NxUserRaycastReport& report, NxShapesType shapesType, NxU32 groups=0xffffffff, NxReal maxDist=NX_MAX_F32, NxU32 hintFlags=0xffffffff, const NxGroupsMask* groupsMask=NULL) const = 0;

        /**
        \brief Calls the report's hitCallback() method for all the shapes of type ShapeType intersected by the ray.
        
        hintFlags is a combination of ::NxRaycastBit flags.
        Returns the number of shapes hit. The point of impact is provided as a parameter to hitCallback().

        Note: Make certain that the direction vector of NxRay is normalized.

        <h3>Example</h3>

        \include NxUserRaycastReport_Usage.cpp


        \param[in] worldRay The ray to cast in the global frame. <b>Range:</b> See #NxRay
        \param[in] report User callback, to be called when an intersection is encountered.
        \param[in] shapesType Choose if to raycast against static, dynamic or both types of shape. See #NxShapesType.
        \param[in] groups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] maxDist Max distance to check along the ray for intersecting objects. <b>Range:</b> (0,inf) 
        \param[in] hintFlags Allows the user to specify which field of #NxRaycastHit they are interested in. See #NxRaycastBit
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return the number of shapes hit

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see raycastAnyShape() raycastAllBounds() NxRay NxUserRaycastReport NxShapesType NxShape.setGroup() NxRaycastHit
        */
        virtual NxU32                                           raycastAllShapes                (const NxRay& worldRay, NxUserRaycastReport& report, NxShapesType shapesType, NxU32 groups=0xffffffff, NxReal maxDist=NX_MAX_F32, NxU32 hintFlags=0xffffffff, const NxGroupsMask* groupsMask=NULL) const = 0;

        /**
        \brief Returns the first axis aligned bounding box enclosing a shape of type shapeType that is hit along the ray.
        
        The world space intersectin point, and the distance along the ray are also provided.
        hintFlags is a combination of ::NxRaycastBit flags.

        Note: Make certain that the direction vector of NxRay is normalized.

        \param[in] worldRay The ray to cast in the global frame. <b>Range:</b> See #NxRay
        \param[in] shapeType Choose if to raycast against static, dynamic or both types of shape. See #NxShapesType.
        \param[out] hit Description of the intersection. See #NxRaycastHit.
        \param[in] groups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] maxDist Max distance to check along the ray for intersecting objects. <b>Range:</b> (0,inf) 
        \param[in] hintFlags Allows the user to specify which field of #NxRaycastHit they are interested in. See #NxRaycastBit
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return The shape which is hit.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see raycastAllBounds() NxRay NxShapesType NxRaycastHit NxShape.setGroup() NxRaycastBit
        */
        virtual NxShape*                                        raycastClosestBounds    (const NxRay& worldRay, NxShapesType shapeType, NxRaycastHit& hit, NxU32 groups=0xffffffff, NxReal maxDist=NX_MAX_F32, NxU32 hintFlags=0xffffffff, const NxGroupsMask* groupsMask=NULL) const = 0;

        /**
        \brief Returns the first shape of type shapeType that is hit along the ray.
        
        The world space intersectin point, and the distance along the ray are also provided.
        hintFlags is a combination of ::NxRaycastBit flags.

        Note: Make certain that the direction vector of NxRay is normalized.

        \param[in] worldRay The ray to cast in the global frame. <b>Range:</b> See #NxRay
        \param[in] shapeType Choose if to raycast against static, dynamic or both types of shape. See #NxShapesType.
        \param[out] hit Description of the intersection. See #NxRaycastHit.
        \param[in] groups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] maxDist Max distance to check along the ray for intersecting objects. <b>Range:</b> (0,inf) 
        \param[in] hintFlags Allows the user to specify which field of #NxRaycastHit they are interested in. See #NxRaycastBit
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return The shape which is hit.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see raycastAllShapes() NxRay NxShapesType NxRaycastHit NxShape.setGroup() NxRaycastBit
        */
        virtual NxShape*                                        raycastClosestShape             (const NxRay& worldRay, NxShapesType shapeType, NxRaycastHit& hit, NxU32 groups=0xffffffff, NxReal maxDist=NX_MAX_F32, NxU32 hintFlags=0xffffffff, const NxGroupsMask* groupsMask=NULL) const = 0;

//@}
/************************************************************************************************/

/** @name Overlap Testing
*/
//@{

        /**
        \brief Returns the set of shapes overlapped by the world-space sphere.
        
        You can test against static and/or dynamic objects by adjusting 'shapeType'. 
        Shapes are written to the static array 'shapes', which should be big enough to hold 'nbShapes'.
        An alternative is to use the ::NxUserEntityReport callback mechanism.

        The function returns the total number of collided shapes.

        NOTE: this functions only tests against the objects' AABBs!

        \param[in] worldSphere Sphere description in world space. <b>Range:</b> See #NxSphere
        \param[in] shapeType Choose if to intersect with static, dynamic or both types of shape. See #NxShapesType.
        \param[in] nbShapes Number of shapes that the buffer shapes can hold.
        \param[out] shapes Buffer to store intersecting shapes. Should be at least sizeof(NxShape *) * nbShapes.
        \param[in] callback Alternative method to retrieve overlapping shapes. Is called with sets of overlapping shapes.
        \param[in] activeGroups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return the total number of collided shapes.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSphere NxShapesType overlapAABBShapes NxUserEntityReport NxShape.checkOverlapSphere()
        */
        virtual NxU32                                           overlapSphereShapes             (const NxSphere& worldSphere, NxShapesType shapeType, NxU32 nbShapes, NxShape** shapes, NxUserEntityReport<NxShape*>* callback, NxU32 activeGroups=0xffffffff, const NxGroupsMask* groupsMask=NULL) = 0;

        /**
        \brief Returns the set of shapes overlapped by the world-space AABB.
        
        You can test against static and/or dynamic objects by adjusting 'shapeType'. 
        Shapes are written to the static array 'shapes', which should be big enough to hold 'nbShapes'.
        An alternative is to use the ::NxUserEntityReport callback mechanism.

        The function returns the total number of collided shapes.

        NOTE: this functions only tests against the objects' AABBs!

        \param[in] worldBounds Axis Aligned Bounding Box in world space. <b>Range:</b> See #NxBounds3
        \param[in] shapeType Choose if to intersect with static, dynamic or both types of shape. See #NxShapesType.
        \param[in] nbShapes Number of shapes that the buffer shapes can hold.
        \param[out] shapes Buffer to store intersecting shapes. Should be at least sizeof(NxShape *) * nbShapes.
        \param[in] callback Alternative method to retrieve overlapping shapes. Is called with sets of overlapping shapes.
        \param[in] activeGroups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return the total number of collided shapes.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxBounds3 NxShapesType overlapSphereShapes NxUserEntityReport NxShape.checkOverlapAABB()
        */
        virtual NxU32                                           overlapAABBShapes               (const NxBounds3& worldBounds, NxShapesType shapeType, NxU32 nbShapes, NxShape** shapes, NxUserEntityReport<NxShape*>* callback, NxU32 activeGroups=0xffffffff, const NxGroupsMask* groupsMask=NULL) = 0;

        /**
        \brief Returns the set of shapes which are in the negative half space of a number of planes.
        
        This function returns the set of shapes whose axis aligned bounding volumes are in the negative 
        half space(side the normal points away from) of all the planes passed in.
        
        However the set of shapes returned is not conservative, ie additional shapes may be returned which
        do not actually intersect the union of the planes negative half space.

        You can test against static and/or dynamic objects by adjusting 'shapeType'.
        Shapes are written to the static array 'shapes', which should be big enough to hold 'nbShapes'.
        An alternative is to use the ::NxUserEntityReport callback mechanism.

        The function returns the total number of collided shapes.

        This function can be used for view-frustum culling by passing the 6 camera planes to the function.

        \warning Passing more than 32 planes to this function is unsupported and may result in undefined behavior.
        
        \param[in] nbPlanes Number of planes to test. (worldPlanes should contain this many planes)
        \param[in] worldPlanes Set of planes to test. <b>Range:</b> See #NxPlane
        \param[in] shapeType Choose if to intersect with static, dynamic or both types of shape. See #NxShapesType.
        \param[in] nbShapes Number of shapes that the buffer shapes can hold.
        \param[out] shapes Buffer to store intersecting shapes. Should be at least sizeof(NxShape *) * nbShapes.
        \param[in] callback Alternative method to retrieve overlapping shapes. Is called with sets of overlapping shapes.
        \param[in] activeGroups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return the total number of collided shapes.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxPlane overlapAABBShapes() overlapSphereShapes() NxShapesType NxUserEntityReport NxShape.setGroup()
        */

        virtual NxU32                                           cullShapes                              (NxU32 nbPlanes, const NxPlane* worldPlanes, NxShapesType shapeType, NxU32 nbShapes, NxShape** shapes, NxUserEntityReport<NxShape*>* callback, NxU32 activeGroups=0xffffffff, const NxGroupsMask* groupsMask=NULL) = 0;

        /**
        \brief Checks whether a world-space sphere overlaps a shape or not.

        \param[in] worldSphere Sphere description in world space. <b>Range:</b> See #NxSphere
        \param[in] shapeType Choose if to intersect with static, dynamic or both types of shape. See #NxShapesType.
        \param[in] activeGroups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return True if the sphere overlaps a shape.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxSphere NxShapesType overlapSphereShapes NxShape.checkOverlapSphere()
        */
        virtual bool                                            checkOverlapSphere              (const NxSphere& worldSphere, NxShapesType shapeType=NX_ALL_SHAPES, NxU32 activeGroups=0xffffffff, const NxGroupsMask* groupsMask=NULL) = 0;

        /**
        \brief Checks whether a world-space AABB overlaps a shape or not.

        \param[in] worldBounds Axis Aligned Bounding Box in world space. <b>Range:</b> See #NxBounds3
        \param[in] shapeType Choose if to intersect with static, dynamic or both types of shape. See #NxShapesType.
        \param[in] activeGroups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return True if the AABB overlaps a shape.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxBounds3 NxShapesType overlapAABBShapes NxShape.checkOverlapAABB()
        */
        virtual bool                                            checkOverlapAABB                (const NxBounds3& worldBounds, NxShapesType shapeType=NX_ALL_SHAPES, NxU32 activeGroups=0xffffffff, const NxGroupsMask* groupsMask=NULL)        = 0;

        /**
        \brief Checks whether a world-space capsule overlaps something or not.

        \param[in] worldCapsule Capsule description in world space. <b>Range:</b> See #NxCapsule
        \param[in] shapeType Choose if to intersect with static, dynamic or both types of shape. See #NxShapesType.
        \param[in] activeGroups Mask used to filter shape objects. See #NxShape::setGroup
        \param[in] groupsMask Alternative mask used to filter shapes. See #NxShape::setGroupsMask

        \return True if the capsule overlaps a shape.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes

        @see NxCapsule NxShapesType NxShape.setGroup NxShape.setGroupsMask
        */
        virtual bool                                            checkOverlapCapsule             (const NxCapsule& worldCapsule, NxShapesType shapeType=NX_ALL_SHAPES, NxU32 activeGroups=0xffffffff, const NxGroupsMask* groupsMask=NULL)       = 0;

        //virtual       NxU32                                           overlapAABBTriangles    (const NxBounds3& worldBounds, NxArraySDK<NxTriangle>& worldTriangles) = 0;
//@}
/************************************************************************************************/
        
/** @name Fluids
*/
//@{

#if NX_USE_FLUID_API
        
        /**
        Not available in the current release.
        Creates a fluid in this scene. NxFluidDesc::isValid() must return true.

        \param[in] fluidDesc Description of the fluid object to create. See #NxFluidDesc.
        \return The new fluid.
        
        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual NxFluid*                                        createFluid(const NxFluidDesc& fluidDesc) = 0;

        /**
        Not available in the current release.
        Deletes the specified fluid. The fluid must be in this scene.
        Do not keep a reference to the deleted instance.

        \param[in] fluid Fluid to release.

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual void                                            releaseFluid(NxFluid& fluid)                    = 0;

        /**
        Not available in the current release.
        \return the number of fluids.

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual NxU32                                           getNbFluids()           const           = 0;

        /**
        Not available in the current release.
        \return an array of fluid pointers with size getNbFluids().

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual NxFluid**                                       getFluids()                                             = 0;

        /**
        Not available in the current release.
        Creates an implicit mesh in this scene. NxImplicitMeshDesc::isValid() must return true.

        \param[in] implMesh Descriptor for the Implicit mesh to create.
        \return The new implicit mesh.

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : No
        \li PS3  : No
        \li XB360: No
        */
        virtual NxImplicitMesh*                         createImplicitMesh(const NxImplicitMeshDesc& implMesh)  = 0;

        /**
        Not available in the current release.
        Deletes the specified implicit mesh. The implicit mesh must be in this scene.
        Do not keep a reference to the deleted instance.

        \param[in] implMesh Implicit mesh to release.

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : No
        \li PS3  : No
        \li XB360: No
        */
        virtual void                                            releaseImplicitMesh(NxImplicitMesh& implMesh)                   = 0;

        /**
        Not available in the current release.
        \return the number of implicit meshes.

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : No
        \li PS3  : No
        \li XB360: No
        */
        virtual NxU32                                           getNbImplicitMeshes() const                                             = 0;

        /**
        Not available in the current release.
        \return an array of implicit mesh pointers with size getNbImplicitMeshes().

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : No
        \li PS3  : No
        \li XB360: No
        */
        virtual NxImplicitMesh**                        getImplicitMeshes()                                                             = 0;

        /**
        Not available in the current release.
        Create a triangle mesh for fluid collision with static triangles. 
        Stream has to be created with NxCookFluidHardwareMesh(). 

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual         bool                            createFluidHardwareTriangleMesh(NxStream& stream)       = 0;

        /**
        Not available in the current release.
        @see NxSceneDesc.simType

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual         NxU32                           getSimType() const                                                                      = 0;

        /**
        Not available in the current release.
        @see NxSceneDesc.hwSceneType

        <b>Platform:</b>
        \li PC SW: No
        \li PPU  : Yes
        \li PS3  : No
        \li XB360: No
        */
        virtual         NxU32                           getHwSceneType() const                                                          = 0;
#endif

//@}
/************************************************************************************************/

        /**
        \brief This is a query to see if the scene is in a state that allows the application to update scene state.

        \return True if the scene can be written by the application.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes
        */
        virtual bool                                            isWritable()    = 0;

        /**
        \brief Advances the simulation by an elapsedTime time.
        
        If elapsedTime is large, it is internally subdivided according to parameters provided with the 
        #setTiming() method. See #setTiming() for a more detailed discussion of the elapsedTime parameter 
        and time stepping behavior.
 
        Calls to simulate() should pair with calls to fetchResults():
        Each fetchResults() invocation corresponds to exactly one simulate()
        invocation; calling simulate() twice without an intervening fetchResults()
        or fetchResults() twice without an intervening simulate() causes an error
        condition.
 
        scene->simulate();
        ...do some processing until physics is computed...
        scene->fetchResults();
        ...now results of run may be retrieved.
 
        Applications should not modify physics objects between calls to
        simulate() and fetchResults();
 
        This method replaces startRun().
        

        \param[in] elapsedTime Amount of time to advance simulation by. <b>Range:</b> (0,inf)

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see fetchResults() checkResults()
        */
        virtual void                                            simulate(NxReal elapsedTime)            = 0;
        
        /**
        \brief This checks to see if the part of the simulation run whose results you are interested in has completed.

        This does not cause the data available for reading to be updated with the results of the simulation, it is simply a status check.
        The bool will allow it to either return immediately or block waiting for the condition to be met so that it can return true

        This method replaces wait()
        
        \param[in] status The part of the simulation to check (eg NX_RIGID_BODY_FINISHED). See #NxSimulationStatus.
        \param[in] block When set to true will block until the condition is met.
        \return True if the results are available.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see simulate() fetchResults()
        */
        virtual bool                                            checkResults(NxSimulationStatus status, bool block = false)     = 0;

        /**
        This is the big brother to checkResults() it basically does the following:
        
        \code
        if ( checkResults(enum, block) )
        {
                fire appropriate callbacks
                swap buffers
                if (CheckResults(all_enums, false))
                        make IsWritable() true
                return true
        }
        else
                return false

        \endcode

        \param[in] status The part of the simulation to fetch results for (eg NX_RIGID_BODY_FINISHED). See #NxSimulationStatus.
        \param[in] block When set to true will block until the condition is met.
        \param[in] errorState When non-zero will return an error value if an internal fatal error condition is detected.
        \return True if the results have been fetched.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes

        @see simulate() checkResults()
        */
        virtual bool                                            fetchResults(NxSimulationStatus status, bool block = false, NxU32 *errorState = 0)      = 0;

        /**
        Flush internal caches.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : Yes
        \li PS3  : Yes
        \li XB360: Yes
        */
        virtual void                                            flushCaches()   = 0;

        /**
        Accesses internal profiler.  If clearData is true, the profile counters are reset.  You will most likely want to call readProfileData(true)
        right after calling fetchResults().  If that is not the time you want to read out the data, just call readProfileData(false) at some other place
        in your code.

        <b>Platform:</b>
        \li PC SW: Yes
        \li PPU  : No
        \li PS3  : Yes
        \li XB360: Yes
        */
        virtual const NxProfileData *           readProfileData(bool clearData) = 0;

        void*   userData;       //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
        };

/** @} */
#endif


//AGCOPYRIGHTBEGIN
///////////////////////////////////////////////////////////////////////////
// Copyright © 2005 AGEIA Technologies.
// All rights reserved. www.ageia.com
///////////////////////////////////////////////////////////////////////////
//AGCOPYRIGHTEND