.. _autosleep:

=========
AutoSleep
=========

AutoSleep is a functionality for putting bodies which are not moving (below a certain threshold) to sleep. This means that the solver will no longer take these objects into account, hence reducing the CPU usage substantially.

A body can be put to sleep if its *absolute* velocity/acceleration goes below a certain threshold. AutoSleep is enabled for the system with a call to:

.. code-block:: c++

  agxSDK::SimulationRef simulation = new agxSDK::Simulation;
  agx::AutoSleep *autoSleep = simulation->getDynamicsSystem()->getAutoSleep();
  // Enable autosleep functionality
  autoSleep->setEnable(true);

AutoSleep also has to be enabled for each body:

.. code-block:: c++

  agx::RigidBodyRef body = new agx::RigidBody
  body->getAutoSleepProperties()->setEnable(true); // Enable AutoSleep for this body

A body will be awaken if

-	Another non-sleeping body get into contact with its geometry
-	Another body attached by a constraint is awaken
-	Explicit awakened through an API call

A body can be explicitly awakened through a call to:

.. code-block:: c++

  body->getAutoSleepProperties()->setSleeping( false );

---------
Threshold
---------

The acceleration, velocity and time threshold can be set globally for AutoSleep:

.. code-block:: c++

  // When linear velocity goes below 0.3m/s it will be considered for sleeping
  autoSleep->getThreshold()->setVelocity(0.3);

  // When angular velocity goes below 0.1rad/s it will be considered for sleeping
  autoSleep->getThreshold()->setAngularVelocity(0.1);

  // When velocity AND acceleration has been below threshold for 0.7 seconds the body
  // will fall to sleep
  autoSleep->getThreshold()->setTime( 0.7 );

Or locally per body:

.. code-block:: c++

  // Create an AutoSleepThreshold object and set the values
  agx::AutoSleepThresholdRef t = new agx::AutoSleepThreshold;
  t->setVelocity(0.1);
  t->setAngularVelocity(0.1);
  t->setTime(2.0);

  // Attach it to a body
  body->setAutoSleepThreshold( t );

  // Several bodies can share the same AutoSleepThreshold
  body2->setAutoSleepThreshold( t );