[ODE] New Auto-disable feature: "Average Sampling Mode"

[David Walters]

Hi, I'm writing this mail to clarify what has changed in the
auto-disable system in the last day.

With credit to Christoph Beyer for the initial implementation, I have
made the auto disable system work such that by default the method of
the classic "instantaneous" auto-disabling system you're all used to
is used to determine if a body should disable.

What Christoph has allowed us to do is expand this into a system where
a number of samples can be captured before a threshold determination
is made. This smoothing should help prevent any jittering in your
simulation from preventing bodies from disabling due to a momentary
spike in velocity.

>From the ODE user's point of view - the API has grown to add two more
function pairs:


//
// Default values for newly created bodies.
//

// *** How many samples to take before evaluating?
ODE_API int dWorldGetAutoDisableAverageSamplesCount (dWorldID);
ODE_API void dWorldSetAutoDisableAverageSamplesCount (dWorldID,
       unsigned int average_samples_count );

//
// Per-body adjustment, at any time.
//

// *** How many samples to take before evaluating?
ODE_API int dBodyGetAutoDisableAverageSamplesCount (dBodyID);
ODE_API void dBodySetAutoDisableAverageSamplesCount (dBodyID,
       unsigned int average_samples_count );


(n.b. disregard other mails prior to this regarding API changes, most
of those functions have been rendered unnecessary by the unification
process)


Both function pairs are very similar, and just like the pre-existing
auto-disable functions the 'world' pair applies to all newly created
bodies, whereas the 'body' pair allow specific tweaking for each body
separately.

By default the sample count is 1. This will set the disable system to
look only at instantaneous velocities - with a fast path through the
code for this method so as to not add unnecessary overheads. If you
don't care about this feature, or don't see it helping your simulation
you can completely ignore these new functions.

However to enable averaging you simply raise this figure to tell ODE
how many samples to review before claiming a body is idle. Recommended
values for this will be around 5/10 however YMMV, and it will really
depend on fine tuning.

NOTE: If you set the sample count to zero, no samples are taken and
auto-disabling is not possible - I wonder if there's scope for rolling
together the formal disabling flag with this setting...

Anyway, I hope this has helped clarify the new system

Regards,
David