Open 3D Engine AzFramework API Reference  24.09
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AzPhysics::SceneInterface Class Referenceabstract

Interface to access a Physics Scene with a SceneHandle. More...

#include <PhysicsScene.h>

Public Member Functions

 AZ_RTTI (SceneInterface, "{912CE8D1-7E3E-496F-B7BE-D17F8B30C228}")
 
 AZ_DISABLE_COPY_MOVE (SceneInterface)
 
virtual SceneHandle GetSceneHandle (const AZStd::string &sceneName)=0
 
virtual SceneGetScene (SceneHandle handle)=0
 
virtual void StartSimulation (SceneHandle sceneHandle, float deltatime)=0
 
virtual void FinishSimulation (SceneHandle sceneHandle)=0
 
virtual void SetEnabled (SceneHandle sceneHandle, bool enable)=0
 
virtual bool IsEnabled (SceneHandle sceneHandle) const =0
 
virtual SimulatedBodyHandle AddSimulatedBody (SceneHandle sceneHandle, const SimulatedBodyConfiguration *simulatedBodyConfig)=0
 
virtual SimulatedBodyHandleList AddSimulatedBodies (SceneHandle sceneHandle, const SimulatedBodyConfigurationList &simulatedBodyConfigs)=0
 
virtual SimulatedBodyGetSimulatedBodyFromHandle (SceneHandle sceneHandle, SimulatedBodyHandle bodyHandle)=0
 
virtual SimulatedBodyList GetSimulatedBodiesFromHandle (SceneHandle sceneHandle, const SimulatedBodyHandleList &bodyHandles)=0
 
virtual void RemoveSimulatedBody (SceneHandle sceneHandle, SimulatedBodyHandle &bodyHandle)=0
 
virtual void RemoveSimulatedBodies (SceneHandle sceneHandle, SimulatedBodyHandleList &bodyHandles)=0
 
virtual void EnableSimulationOfBody (SceneHandle sceneHandle, SimulatedBodyHandle bodyHandle)=0
 
virtual void DisableSimulationOfBody (SceneHandle sceneHandle, SimulatedBodyHandle bodyHandle)=0
 
virtual JointHandle AddJoint (SceneHandle sceneHandle, const JointConfiguration *jointConfig, SimulatedBodyHandle parentBody, SimulatedBodyHandle childBody)=0
 
virtual JointGetJointFromHandle (SceneHandle sceneHandle, JointHandle jointHandle)=0
 
virtual void RemoveJoint (SceneHandle sceneHandle, JointHandle jointHandle)=0
 
virtual SceneQueryHits QueryScene (SceneHandle sceneHandle, const SceneQueryRequest *request)=0
 
virtual bool QueryScene (SceneHandle sceneHandle, const SceneQueryRequest *request, SceneQueryHits &result)=0
 
virtual SceneQueryHitsList QuerySceneBatch (SceneHandle sceneHandle, const SceneQueryRequests &requests)=0
 
virtual bool QuerySceneAsync (SceneHandle sceneHandle, SceneQuery::AsyncRequestId requestId, const SceneQueryRequest *request, SceneQuery::AsyncCallback callback)=0
 
virtual bool QuerySceneAsyncBatch (SceneHandle sceneHandle, SceneQuery::AsyncRequestId requestId, const SceneQueryRequests &requests, SceneQuery::AsyncBatchCallback callback)=0
 
virtual void SuppressCollisionEvents (SceneHandle sceneHandle, const SimulatedBodyHandle &bodyHandleA, const SimulatedBodyHandle &bodyHandleB)=0
 
virtual void UnsuppressCollisionEvents (SceneHandle sceneHandle, const SimulatedBodyHandle &bodyHandleA, const SimulatedBodyHandle &bodyHandleB)=0
 
virtual void SetGravity (SceneHandle sceneHandle, const AZ::Vector3 &gravity)=0
 
virtual AZ::Vector3 GetGravity (SceneHandle sceneHandle) const =0
 
virtual void RegisterSceneConfigurationChangedEventHandler (SceneHandle sceneHandle, SceneEvents::OnSceneConfigurationChanged::Handler &handler)=0
 
virtual void RegisterSimulationBodyAddedHandler (SceneHandle sceneHandle, SceneEvents::OnSimulationBodyAdded::Handler &handler)=0
 
virtual void RegisterSimulationBodyRemovedHandler (SceneHandle sceneHandle, SceneEvents::OnSimulationBodyRemoved::Handler &handler)=0
 
virtual void RegisterSimulationBodySimulationEnabledHandler (SceneHandle sceneHandle, SceneEvents::OnSimulationBodySimulationEnabled::Handler &handler)=0
 
virtual void RegisterSimulationBodySimulationDisabledHandler (SceneHandle sceneHandle, SceneEvents::OnSimulationBodySimulationDisabled::Handler &handler)=0
 
virtual void RegisterSceneSimulationStartHandler (SceneHandle sceneHandle, SceneEvents::OnSceneSimulationStartHandler &handler)=0
 
virtual void RegisterSceneSimulationFinishHandler (SceneHandle sceneHandle, SceneEvents::OnSceneSimulationFinishHandler &handler)=0
 
virtual void RegisterSceneActiveSimulatedBodiesHandler (SceneHandle sceneHandle, SceneEvents::OnSceneActiveSimulatedBodiesEvent::Handler &handler)=0
 
virtual void RegisterSceneCollisionEventHandler (SceneHandle sceneHandle, SceneEvents::OnSceneCollisionsEvent::Handler &handler)=0
 
virtual void RegisterSceneTriggersEventHandler (SceneHandle sceneHandle, SceneEvents::OnSceneTriggersEvent::Handler &handler)=0
 
virtual void RegisterSceneGravityChangedEvent (SceneHandle sceneHandle, SceneEvents::OnSceneGravityChangedEvent::Handler &handler)=0
 

Detailed Description

Interface to access a Physics Scene with a SceneHandle.

Member Function Documentation

◆ AddJoint()

virtual JointHandle AzPhysics::SceneInterface::AddJoint ( SceneHandle  sceneHandle,
const JointConfiguration jointConfig,
SimulatedBodyHandle  parentBody,
SimulatedBodyHandle  childBody 
)
pure virtual

Add a joint to the Scene.

Parameters
sceneHandleA handle to the scene to add / remove the joint.
jointConfigThe config of the joint.
parentBodyThe parent body of the joint.
childBodyThe child body of the joint
Returns
Returns a handle to the created joint. Will return AzPhyiscs::InvalidJointHandle if it fails.

◆ AddSimulatedBodies()

virtual SimulatedBodyHandleList AzPhysics::SceneInterface::AddSimulatedBodies ( SceneHandle  sceneHandle,
const SimulatedBodyConfigurationList &  simulatedBodyConfigs 
)
pure virtual

Add a set of simulated bodied to the Scene.

Parameters
sceneHandleA handle to the scene to Add the simulated bodies to.
simulatedBodyConfigsThe list of simulated body configs.
Returns
Returns a list of handles to the created Simulated bodies. Will be in the same order as supplied in simulatedBodyConfigs. If the scene handle is invalid, this will return an empty list. If one fails, that index will be set to AzPhyiscs::InvalidSimulatedBodyHandle.

◆ AddSimulatedBody()

virtual SimulatedBodyHandle AzPhysics::SceneInterface::AddSimulatedBody ( SceneHandle  sceneHandle,
const SimulatedBodyConfiguration simulatedBodyConfig 
)
pure virtual

Add a simulated body to the Scene.

Parameters
sceneHandleA handle to the scene to add the requested simulated body.
simulatedBodyConfigThe config of the simulated body.
Returns
Returns a handle to the created Simulated body. Will return AzPhyiscs::InvalidSimulatedBodyHandle if it fails.

◆ EnableSimulationOfBody()

virtual void AzPhysics::SceneInterface::EnableSimulationOfBody ( SceneHandle  sceneHandle,
SimulatedBodyHandle  bodyHandle 
)
pure virtual

Enable / Disable simulation of the requested body. By default all bodies added are enabled. Disabling simulation the body will no longer be affected by any forces, collisions, or found with scene queries.

Parameters
sceneHandleA handle to the scene to enable / disable the requested simulated body.
bodyHandleThe handle of the simulated body to enable / disable.

◆ FinishSimulation()

virtual void AzPhysics::SceneInterface::FinishSimulation ( SceneHandle  sceneHandle)
pure virtual

Complete the simulation process. As an example, this is a good place to wait for any work to complete that was triggered in StartSimulation, or swap buffers if double buffering.

Parameters
sceneHandleThe SceneHandle of the scene to use.

◆ GetGravity()

virtual AZ::Vector3 AzPhysics::SceneInterface::GetGravity ( SceneHandle  sceneHandle) const
pure virtual

Get the Gravity of the given Scene.

Parameters
sceneHandleA handle to the scene to get the gravity vector of.
Returns
A Vector3 of the gravity used in the Scene, will return a Zero Vector if sceneHandle is invalid or not found.

◆ GetJointFromHandle()

virtual Joint* AzPhysics::SceneInterface::GetJointFromHandle ( SceneHandle  sceneHandle,
JointHandle  jointHandle 
)
pure virtual

Get the Raw pointer to the requested joint.

Parameters
sceneHandleA handle to the scene to get the simulated bodies from.
jointHandleA handle to the joint to retrieve the raw pointer.
Returns
A raw pointer to the Joint body. If the either handle is invalid this will return null.

◆ GetScene()

virtual Scene* AzPhysics::SceneInterface::GetScene ( SceneHandle  handle)
pure virtual

Get the Scene of the requested SceneHandle.

Parameters
handleThe SceneHandle of the requested scene.
Returns
Returns a Scene pointer if found, otherwise nullptr.

◆ GetSceneHandle()

virtual SceneHandle AzPhysics::SceneInterface::GetSceneHandle ( const AZStd::string &  sceneName)
pure virtual

Returns a Scene Handle connected to the given scene name.

Parameters
sceneNameThe name of the scene to look up.
Returns
Will return a SceneHandle to a Scene connected with the given name, otherwise will return InvalidSceneHandle.

◆ GetSimulatedBodiesFromHandle()

virtual SimulatedBodyList AzPhysics::SceneInterface::GetSimulatedBodiesFromHandle ( SceneHandle  sceneHandle,
const SimulatedBodyHandleList &  bodyHandles 
)
pure virtual

Get the Raw pointer to the set of requested simulated bodies.

Parameters
sceneHandleA handle to the scene to get the simulated bodies from.
bodyHandlesA list of simulated body handles to retrieve the raw pointers.
Returns
A list of raw pointers to the Simulated bodies requested. If the scene handle is invalid this will return an empty list. If a simulated body handle is invalid, that index in the list will be null.

◆ GetSimulatedBodyFromHandle()

virtual SimulatedBody* AzPhysics::SceneInterface::GetSimulatedBodyFromHandle ( SceneHandle  sceneHandle,
SimulatedBodyHandle  bodyHandle 
)
pure virtual

Get the Raw pointer to the requested simulated body.

Parameters
sceneHandleA handle to the scene to get the simulated bodies from.
bodyHandleA handle to the simulated body to retrieve the raw pointer.
Returns
A raw pointer to the Simulated body. If the either handle is invalid this will return null.

◆ IsEnabled()

virtual bool AzPhysics::SceneInterface::IsEnabled ( SceneHandle  sceneHandle) const
pure virtual

Check if this Scene is currently Enabled.

Parameters
sceneHandleThe SceneHandle of the scene to use.
Returns
When true the Scene is enabled and will execute its simulation tick when StartSimulation is called. When false, StartSimulation will not execute or the SceneHandle is invalid.

◆ QueryScene() [1/2]

virtual SceneQueryHits AzPhysics::SceneInterface::QueryScene ( SceneHandle  sceneHandle,
const SceneQueryRequest request 
)
pure virtual

Make a blocking query into the scene.

Parameters
sceneHandleA handle to the scene to make the scene query with.
requestThe request to make. Should be one of RayCastRequest || ShapeCastRequest || OverlapRequest
Returns
Returns a structure that contains a list of Hits. Depending on flags set in the request, this may only contain 1 result.

◆ QueryScene() [2/2]

virtual bool AzPhysics::SceneInterface::QueryScene ( SceneHandle  sceneHandle,
const SceneQueryRequest request,
SceneQueryHits result 
)
pure virtual

Make a blocking query into the scene.

Parameters
sceneHandleA handle to the scene to make the scene query with.
requestThe request to make. Should be one of RayCastRequest || ShapeCastRequest || OverlapRequest
resultA structure that contains a list of Hits. Depending on flags set in the request, this may only contain 1 result.
Returns
Returns true if there is at least one hit.

◆ QuerySceneAsync()

virtual bool AzPhysics::SceneInterface::QuerySceneAsync ( SceneHandle  sceneHandle,
SceneQuery::AsyncRequestId  requestId,
const SceneQueryRequest request,
SceneQuery::AsyncCallback  callback 
)
pure virtual

Make a non-blocking query into the scene.

Parameters
sceneHandleA handle to the scene to make the scene query with.
requestIdA user defined value to identify the request when the callback is called.
requestThe request to make. Should be one of RayCastRequest || ShapeCastRequest || OverlapRequest
callbackThe callback to trigger when the request is complete.
Returns
Returns If the request was queued successfully. If returns false, the callback will never be called.

◆ QuerySceneAsyncBatch()

virtual bool AzPhysics::SceneInterface::QuerySceneAsyncBatch ( SceneHandle  sceneHandle,
SceneQuery::AsyncRequestId  requestId,
const SceneQueryRequests &  requests,
SceneQuery::AsyncBatchCallback  callback 
)
pure virtual

Make a non-blocking query into the scene.

Parameters
sceneHandleA handle to the scene to make the scene query with.
requestIdA user defined valid to identify the request when the callback is called.
requestsA list of requests to make. Each entry should be one of RayCastRequest || ShapeCastRequest || OverlapRequest
callbackThe callback to trigger when all the request are complete.
Returns
Returns If the request was queued successfully. If returns false, the callback will never be called.

◆ QuerySceneBatch()

virtual SceneQueryHitsList AzPhysics::SceneInterface::QuerySceneBatch ( SceneHandle  sceneHandle,
const SceneQueryRequests &  requests 
)
pure virtual

Make many blocking queries into the scene.

Parameters
sceneHandleA handle to the scene to make the scene query with.
requestsA list of requests to make. Each entry should be one of RayCastRequest || ShapeCastRequest || OverlapRequest
Returns
Returns a list of SceneQueryHits. Will be in the same order as supplied in SceneQueryRequests.

◆ RegisterSceneActiveSimulatedBodiesHandler()

virtual void AzPhysics::SceneInterface::RegisterSceneActiveSimulatedBodiesHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSceneActiveSimulatedBodiesEvent::Handler &  handler 
)
pure virtual

Register a handler to receive an event with a list of SimulatedBodyHandles that updated this scene tick.

Note
This will fire after the OnSceneSimulationStartEvent and before the OnSceneSimulationFinishEvent when SceneConfiguration::m_enableActiveActors is true.
Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSceneCollisionEventHandler()

virtual void AzPhysics::SceneInterface::RegisterSceneCollisionEventHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSceneCollisionsEvent::Handler &  handler 
)
pure virtual

Register a handler to receive all collision events in the scene.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSceneConfigurationChangedEventHandler()

virtual void AzPhysics::SceneInterface::RegisterSceneConfigurationChangedEventHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSceneConfigurationChanged::Handler &  handler 
)
pure virtual

Register a handler to receive an event when the SceneConfiguration changes.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSceneGravityChangedEvent()

virtual void AzPhysics::SceneInterface::RegisterSceneGravityChangedEvent ( SceneHandle  sceneHandle,
SceneEvents::OnSceneGravityChangedEvent::Handler &  handler 
)
pure virtual

Register a handler to receive a notification when the Scene's gravity has changed.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSceneSimulationFinishHandler()

virtual void AzPhysics::SceneInterface::RegisterSceneSimulationFinishHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSceneSimulationFinishHandler &  handler 
)
pure virtual

Register a handler to receive an event when Scene::FinishSimulation is called.

Note
This may fire multiple times per frame.
Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSceneSimulationStartHandler()

virtual void AzPhysics::SceneInterface::RegisterSceneSimulationStartHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSceneSimulationStartHandler &  handler 
)
pure virtual

Register a handler to receive an event when Scene::StartSimulation is called.

Note
This may fire multiple times per frame.
Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSceneTriggersEventHandler()

virtual void AzPhysics::SceneInterface::RegisterSceneTriggersEventHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSceneTriggersEvent::Handler &  handler 
)
pure virtual

Register a handler to receive all trigger events in the scene.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSimulationBodyAddedHandler()

virtual void AzPhysics::SceneInterface::RegisterSimulationBodyAddedHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSimulationBodyAdded::Handler &  handler 
)
pure virtual

Register a handler to receive an event when a Simulated body is added to the Scene.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSimulationBodyRemovedHandler()

virtual void AzPhysics::SceneInterface::RegisterSimulationBodyRemovedHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSimulationBodyRemoved::Handler &  handler 
)
pure virtual

Register a handler to receive an event when a Simulated body is removed from the Scene.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSimulationBodySimulationDisabledHandler()

virtual void AzPhysics::SceneInterface::RegisterSimulationBodySimulationDisabledHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSimulationBodySimulationDisabled::Handler &  handler 
)
pure virtual

Register a handler to receive an event when a Simulated body has its simulation disabled in the Scene.

Parameters
sceneHandleA handle to the scene to register the event with.
handlerThe handler to receive the event.

◆ RegisterSimulationBodySimulationEnabledHandler()

virtual void AzPhysics::SceneInterface::RegisterSimulationBodySimulationEnabledHandler ( SceneHandle  sceneHandle,
SceneEvents::OnSimulationBodySimulationEnabled::Handler &  handler 
)
pure virtual

Register a handler to receive an event when a Simulated body has its simulation enabled in the Scene.

Parameters
sceneHandleA handle to the scene to register the event with. This will only trigger if the simulated body was disabled, when first added to a scene SceneEvents::OnAnySimulationBodyCreated will trigger instead.
handlerThe handler to receive the event.

◆ RemoveJoint()

virtual void AzPhysics::SceneInterface::RemoveJoint ( SceneHandle  sceneHandle,
JointHandle  jointHandle 
)
pure virtual

Remove a joint from the Scene.

Parameters
sceneHandleA handle to the scene to add / remove the joint.
jointHandleA handle to the joint being removed.

◆ RemoveSimulatedBodies()

virtual void AzPhysics::SceneInterface::RemoveSimulatedBodies ( SceneHandle  sceneHandle,
SimulatedBodyHandleList &  bodyHandles 
)
pure virtual

Remove a list of simulated bodies from the Scene.

Parameters
sceneHandleA handle to the scene to remove the simulated bodies from.
bodyHandlesA list of simulated body handles to be removed. All handles will be set to AzPhysics::InvalidSimulatedBodyHandle as they're no longer valid.

◆ RemoveSimulatedBody()

virtual void AzPhysics::SceneInterface::RemoveSimulatedBody ( SceneHandle  sceneHandle,
SimulatedBodyHandle &  bodyHandle 
)
pure virtual

Remove a simulated body from the Scene.z

Parameters
sceneHandleA handle to the scene to remove the requested simulated body.
bodyHandleA handle to the simulated body being removed. This will be set to AzPhysics::InvalidSimulatedBodyHandle as they're no longer valid.

◆ SetEnabled()

virtual void AzPhysics::SceneInterface::SetEnabled ( SceneHandle  sceneHandle,
bool  enable 
)
pure virtual

Enable or Disable this Scene's Simulation tick. Default is Enabled.

Parameters
sceneHandleThe SceneHandle of the scene to use.
enableWhen true the Scene will execute its simulation tick when StartSimulation is called. When false, StartSimulation will not execute.

◆ SetGravity()

virtual void AzPhysics::SceneInterface::SetGravity ( SceneHandle  sceneHandle,
const AZ::Vector3 &  gravity 
)
pure virtual

Set the Gravity of the given Scene.

Parameters
sceneHandleA handle to the scene to set the gravity vector of. @Param The new gravity vector to be used in the Scene

◆ StartSimulation()

virtual void AzPhysics::SceneInterface::StartSimulation ( SceneHandle  sceneHandle,
float  deltatime 
)
pure virtual

Start the simulation process. As an example, this is a good place to trigger and queue any long running work in separate threads.

Parameters
sceneHandleThe SceneHandle of the scene to use.
deltatimeThe time in seconds to step the simulation for.

◆ SuppressCollisionEvents()

virtual void AzPhysics::SceneInterface::SuppressCollisionEvents ( SceneHandle  sceneHandle,
const SimulatedBodyHandle &  bodyHandleA,
const SimulatedBodyHandle &  bodyHandleB 
)
pure virtual

Registers a pair of simulated bodies for which collisions should be suppressed. Making multiple requests with the same pair result are dropped. To remove the suppression call UnsuppressCollisionEvents with the pair. The order of the bodies do not matter, {body0, body1} collision pair is equal to {body1, body0}.

Parameters
sceneHandleA handle to the scene to register the collision pair with.
bodyHandleAA handle to a simulated body.
bodyHandleBA handle to a simulated body.

◆ UnsuppressCollisionEvents()

virtual void AzPhysics::SceneInterface::UnsuppressCollisionEvents ( SceneHandle  sceneHandle,
const SimulatedBodyHandle &  bodyHandleA,
const SimulatedBodyHandle &  bodyHandleB 
)
pure virtual

Unregisters a pair of simulated bodies for which collisions should be suppressed. Making multiple requests with the same pair result are dropped. To add a suppression call SuppressCollisionEvents with the pair. The order of the bodies do not matter, {body0, body1} collision pair is equal to {body1, body0}.

Parameters
sceneHandleA handle to the scene to unregister the collision pair with.
bodyHandleAA handle to a simulated body.
bodyHandleBA handle to a simulated body.

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