This is never for inline references to parameters, only for starting parameter
documentation blocks. The "@p" command is for this, although unfortunately
Doxygen doesn't actually do anything with it and it's just an alias for code
text.
Original code is of questionable historical provenance, and
was needlessly (it seems) complexity. New code is relatively
simple arithmetic linear interpolation.
This uses boost::multiprecision::int512_t when multiplying and dividing by the numerator
and denominator of a ratio_t. 128 bits would be sufficient but for some reason, the boost
docs show the 512 bit variant being very slightly faster.
This is a better solution than using a double, which although it will prevent overflow
has fairly limited resolution.
Region fades would sometimes get in a mode with weird behaviour. They
would be drawn in 2d with crossing lines, mainly moving back and forth
horizontally - not as a function of time. It would sound as it looked.
The fade would sometimes jump around when resizing. It could be worked
around by resetting the fade shape. It turned out the problem could be
reproduced by making minute long fades.
This change fixes or works around the problem.
Back story:
timepos_t (in temporal/timeline.h) uses 62 bit for integer value and the
max value is thus 4611686018427387904 ~ 5e18. timepos_t counts
superclocks, where superclock_ticks_per_second is 56448000 ~ 6e7. It can
thus store up to 8e10 seconds - thousands of years.
ratio_t (in temporal/types.h) can represent fractions as 64 bit (signed)
numerator and denominator. timepos_t avoids floating point operations,
but has operator* with ratio_t. To avoid crazy loss of precision it will
multiply the superclock count with the numerator before dividing with
the denominator.
Audio region fade in and out uses a number of increasing timepos_t
values (in a ControlList) up to the length of fade. When dragging to
resize, these values are (in_x_scale) multiplied with the ratio_t of the
new and old fade length. The problem is that the 62 bits will overflow
if using fades more than sqrt(5e18) ~ 2e9 superclock ticks ~ 38 seconds.
It will overflow into the "beat" flag and (at 58 seconds) into the sign
bit. The timepos_t values in the fade will thus jump and can be negative
or change to count beats.
To work around that problem, this changeset just use floating point
values for scaling the timepos_t values. All scaled values are stored as
integer anyway, so it should not make any actual difference for this use
case. There might however be other uses of ControlList where it matters.
As an implementation detail of this "workaround" of using double, it
could perhaps also be nice to implement timepos_t operator* (or
operator*=) for double. But I'm not sure we want floating point support
in timepos_t.
An alternative (and better) solution would be to convince the fraction
multiplication to use 128 bits. It is essential to avoid overflow -
mainly in static analysis, alternatively as runtime checks or asserts.
Code within the method was using @param start_time rather than start, which is a modified
value required to generate the correct results.
This comment also contains some logical reordering, optimization and commenting
on this rather complex method.
Region-gain (unlike other automation) is specific to the
region and independent of the source. Region::start() offset
does not apply. When region-start is trimmed the region's
envelope is modified (not just offset). The event-list is truncated.
Any audio-region envelope does (and must) have a point exactly
at the start and end of the region.
truncate_start() can thus calculate the earliest position of
valid events with the new length relative to the last event.
The mathematical operator for that is subtraction, not distance.
This fixes segfaults as well as corrupt listes when copy/pasting
due to invalid iterators.
::mark_dirty() must be called with WriterLock, and
::rt_safe_earliest_event_linear_unlocked() must not be called
while _events is being modified. The Sequence iterator
(only user of that function) does not ensure this. Only the
sequence read-lock is taken.
These are longer be used since Seuqnce has a "force_discrete"
boolen that needs to be taken into account in addition to
user-configurable ControlList _interpolation mode.
