class GainControl

Class that controls audio gain. This essentially wraps the functionality of a FIDL GainControl.

Gain can be controlled in two different ways:

1. by `ScheduleGain` and `ScheduleMute` functions:

These functions can be used to schedule gain and mute changes at a specified reference time

to be applied. When scheduling gain, an optional gain ramp parameter can be used, which

would apply a ramp with a specified duration, starting from the scheduled reference time,

from the gain value at the reference time, to the specified target gain. Note that the

starting gain value of the ramp is computed at the time of the next `Advance` call, in order

to make sure that all scheduled changes are taken into account at that reference time,

regardless of the order of the schedule calls.

2. by `SetGain` and `SetMute` functions:

These functions correspond to the "ASAP" RealTime option in FIDL GainControl API. They can

be used to directly apply a change in gain or mute. Note that, similar to scheduling gains,

an optional gain ramp parameter can be used when setting a change in gain, which would start

the specified ramp immediately in the next `Advance` call.

The following are guaranteed when applying gain changes:

* `ScheduleGain` and `ScheduleMute` will always be applied in order of their reference times,

regardless of which order they were called. For example, these calls with decreasing

reference times below will be applied in the opposite order of their original call order:

```

ScheduleGain(3, 3.0f);

ScheduleGain(2, 2.0f);

ScheduleMute(1, true);

```

* Changes that are scheduled at the same reference time will be applied in their call order.

For example, calls below will result in a final gain value of 2.0f, which is muted:

```

ScheduleGain(5, 3.0f);

ScheduleMute(5, false);

ScheduleGain(5, -10.0f);

ScheduleGain(5, 2.0f);

ScheduleMute(5, true);

```

* Only a single gain ramp can be active at a time, i.e. any ongoing gain ramp at a time will be

replaced by a call that is set to be applied anytime at or after the beginning of the ongoing

ramp. This is not only true for the `ScheduleGain` and `ScheduleMute` calls, but also for the

`SetGain` and `SetMute` calls.

* Changes can be scheduled in the past, where the guarantees above will still be preserved.

That said, all the scheduled changes that were "late" to arrive will be applied before the

pending "ASAP" set changes in the next `Advance` call.

* Likewise, `SetGain` and `SetMute` changes will typically be applied after `ScheduleGain` and

`ScheduleMute` changes that are set to be applied at the same reference time. However, since

`SetGain` and `SetMute` do not expose their reference time, we do *not* recommend mixing

these two types of functions if the call order is of importance to the application.

This class is not safe for concurrent use.