What effect does "wake" have in b2Body::ApplyLinearImpulse?

Question

I am using Box2d v2.3 The following box2d method takes a bool "wake" :

inline void b2Body::ApplyLinearImpulse(const b2Vec2& impulse, const b2Vec2& point, bool wake)

What does it do? Regardless of whether I set it to YES or NO, it doesn't seem to noticeable impact my physics.

Earlier versions of Box2d did not accept the bool - they only took impulse and point.

EDIT: Likewise so does the following method:

inline void b2Body::ApplyForce(const b2Vec2& force, const b2Vec2& point, bool wake)

score 5 · Accepted Answer · edited Jun 20 '20 at 09:12

Taken from the official Box2D manual:

What does sleep mean? Well it is expensive to simulate bodies, so the less we have to simulate the better. When a body comes to rest we would like to stop simulating it.

When Box2D determines that a body (or group of bodies) has come to rest, the body enters a sleep state which has very little CPU overhead. If a body is awake and collides with a sleeping body, then the sleeping body wakes up. Bodies will also wake up if a joint or contact attached to them is destroyed. You can also wake a body manually.

So the sleepmode is a way to improve performance. It makes sense to wake up a body, when you apply a force to it, so in case it is not already awake anyway, it will wake up and be simulated, because that's what you probably want.

In case it is already awake, it doesn't matter. It won't be set to sleep with wake=false and waking it up again, doesn't change anything. To be safe, you should always use wake=true. In the worst case it hurts the performance a little bit, but only for a little while. Then Box2D will set it back to sleep anyway.

I still don't fully understand. In my case the body should already be awake because I am applying a force or impulse to it. Should I set wake to YES or no? — Rahul Iyer, Jan 01 '14 at 12:22

score 3 · Answer 2 · answered Jan 01 '14 at 13:05

Before v2.3.0, the ApplyLinearImpulse(...) function looked like this:

inline void b2Body::ApplyLinearImpulse(const b2Vec2& impulse, const b2Vec2& point)
{
    if (m_type != b2_dynamicBody)
    {
        return;
    }

    if (IsAwake() == false)
    {
        SetAwake(true);
    }
    m_linearVelocity += m_invMass * impulse;
    m_angularVelocity += m_invI * b2Cross(point - m_sweep.c, impulse);
}

So if you applied any force, it automatically woke the body. Regardless of whether it was asleep. You had to test it before hand (calling IsAwake(...) yourself) so you could avoid applying the force if it was asleep.

From the code base for v2.3.0:

inline void b2Body::ApplyLinearImpulse(const b2Vec2& impulse, const b2Vec2& point, bool wake)
{
    if (m_type != b2_dynamicBody)
    {
        return;
    }

    if (wake && (m_flags & e_awakeFlag) == 0)
    {
        SetAwake(true);
    }

    // Don't accumulate velocity if the body is sleeping
    if (m_flags & e_awakeFlag)
    {
        m_linearVelocity += m_invMass * impulse;
        m_angularVelocity += m_invI * b2Cross(point - m_sweep.c, impulse);
    }
}

The new line is the key:

if (wake && (m_flags & e_awakeFlag) == 0)

If wake == true and asleep, then awake the body. If wake == true and not asleep, do nothing. If wake == false and asleep, do nothing. If wake == false and not asleep, do nothing.

This works out to: "Don't apply force to the body if it is already asleep when wake is false."

Was this helpful?

What effect does "wake" have in b2Body::ApplyLinearImpulse?

2 Answers2