2019-01-24 08:43:03 +00:00
|
|
|
|
// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
|
|
|
|
|
|
// See the LICENCE file in the repository root for full licence text.
|
2018-04-13 09:19:50 +00:00
|
|
|
|
|
2022-06-17 07:37:17 +00:00
|
|
|
|
#nullable disable
|
|
|
|
|
|
|
2018-11-02 10:52:40 +00:00
|
|
|
|
namespace osu.Game.Rulesets.UI.Scrolling.Algorithms
|
2018-01-07 03:47:09 +00:00
|
|
|
|
{
|
2018-11-02 10:51:34 +00:00
|
|
|
|
public interface IScrollAlgorithm
|
2018-01-07 03:47:09 +00:00
|
|
|
|
{
|
2018-10-30 09:14:11 +00:00
|
|
|
|
/// <summary>
|
Fix lifetime calculation in overlapping algorithm
Changes to lifetime calculation in scrolling rulesets introduced in
#7367, which aimed to account for the distance between hit objects'
origin and its edge entering the scrolling area, fixed some issues with
hitobjects appearing abruptly, but also regressed some other scenarios.
Upon investigation, the regression was localised to the overlapping
scroll algorithm. The reason for this was two-fold:
* The previous code used TimeAt() to calculate the time of travel from
the hit object's edge to its origin. For other algorithms, that time
can be accurately reconstructed, because they don't have periods of
time where there are multiple hit objects scrolling at different
velocities.
That invariant does not hold for the overlapping algorithm, therefore
it is possible for different values to be technically correct for
TimeAt(). However, the only value that matters for the adjustment
is the one that's indicated by the control point that applies to the
hit object origin, which can be uniquely identified.
* Additionally, the offset returned (even if correct) was applied
externally to the hit object's start time and passed to
GetDisplayStartTime(). In the overlapping algorithm, the choice of
control point used in GetDisplayStartTime() is important, since
the value of the speed multiplier is read within.
Externally rewinding the hit object's start time meant that in some
cases the speed multiplier of the *previous* control point is applied,
which led to hit objects appearing too late if the scrolling rate
decreased.
Because of the above, modify GetDisplayStartTime() to take the offset
into account in all algorithms, and apply the adjustment correctly
inside of them. The constant and sequential algorithms needed no
adjustment from the previous logic, since:
* the constant algorithm disregarded control points, and
* the sequential algorithm would effectively rewind to time = 0,
calculate the absolute distance from time = 0 to the hit object start,
apply the origin offset *to the absolute distance*, and then convert
back to time, applying all control points in sequence. Due to this
it was impossible for control points to get mixed up while
calculating.
As for the overlapping algorithm, the high-level logic is as follows:
* The distance that the origin has to travel is the length of the scroll
plus the distance from the origin to the object edge.
* The above distance divided by the scroll length gives the relative
scroll lengths that the object has to travel.
* As one relative scroll length takes one time range, the relative
travel length multiplied by the time range gives the absolute travel
time of the object origin.
* Finally, the control point multiplier applicable at origin time is
applied to the whole travel time.
Correctness of the above is demonstrated by visual tests added before
and headless unit tests of the algorithms themselves. The sequential
scroll algorithm was not covered by unit tests, and remains uncovered
due to floating-point inaccuracies that should be addressed separately.
2020-02-06 21:46:31 +00:00
|
|
|
|
/// Given a point in time associated with an object's origin
|
|
|
|
|
|
/// and the spatial distance between the edge and the origin of the object along the scrolling axis,
|
|
|
|
|
|
/// computes the time at which the object initially enters the time range.
|
2018-10-30 09:14:11 +00:00
|
|
|
|
/// </summary>
|
Fix lifetime calculation in overlapping algorithm
Changes to lifetime calculation in scrolling rulesets introduced in
#7367, which aimed to account for the distance between hit objects'
origin and its edge entering the scrolling area, fixed some issues with
hitobjects appearing abruptly, but also regressed some other scenarios.
Upon investigation, the regression was localised to the overlapping
scroll algorithm. The reason for this was two-fold:
* The previous code used TimeAt() to calculate the time of travel from
the hit object's edge to its origin. For other algorithms, that time
can be accurately reconstructed, because they don't have periods of
time where there are multiple hit objects scrolling at different
velocities.
That invariant does not hold for the overlapping algorithm, therefore
it is possible for different values to be technically correct for
TimeAt(). However, the only value that matters for the adjustment
is the one that's indicated by the control point that applies to the
hit object origin, which can be uniquely identified.
* Additionally, the offset returned (even if correct) was applied
externally to the hit object's start time and passed to
GetDisplayStartTime(). In the overlapping algorithm, the choice of
control point used in GetDisplayStartTime() is important, since
the value of the speed multiplier is read within.
Externally rewinding the hit object's start time meant that in some
cases the speed multiplier of the *previous* control point is applied,
which led to hit objects appearing too late if the scrolling rate
decreased.
Because of the above, modify GetDisplayStartTime() to take the offset
into account in all algorithms, and apply the adjustment correctly
inside of them. The constant and sequential algorithms needed no
adjustment from the previous logic, since:
* the constant algorithm disregarded control points, and
* the sequential algorithm would effectively rewind to time = 0,
calculate the absolute distance from time = 0 to the hit object start,
apply the origin offset *to the absolute distance*, and then convert
back to time, applying all control points in sequence. Due to this
it was impossible for control points to get mixed up while
calculating.
As for the overlapping algorithm, the high-level logic is as follows:
* The distance that the origin has to travel is the length of the scroll
plus the distance from the origin to the object edge.
* The above distance divided by the scroll length gives the relative
scroll lengths that the object has to travel.
* As one relative scroll length takes one time range, the relative
travel length multiplied by the time range gives the absolute travel
time of the object origin.
* Finally, the control point multiplier applicable at origin time is
applied to the whole travel time.
Correctness of the above is demonstrated by visual tests added before
and headless unit tests of the algorithms themselves. The sequential
scroll algorithm was not covered by unit tests, and remains uncovered
due to floating-point inaccuracies that should be addressed separately.
2020-02-06 21:46:31 +00:00
|
|
|
|
/// <example>
|
|
|
|
|
|
/// Let's assume the following parameters:
|
|
|
|
|
|
/// <list type="bullet">
|
|
|
|
|
|
/// <item><paramref name="originTime"/> = 7000ms,</item>
|
|
|
|
|
|
/// <item><paramref name="offset"/> = 100px,</item>
|
|
|
|
|
|
/// <item><paramref name="timeRange"/> = 5000ms,</item>
|
|
|
|
|
|
/// <item><paramref name="scrollLength"/> = 1000px</item>
|
|
|
|
|
|
/// </list>
|
|
|
|
|
|
/// and a constant scrolling rate.
|
|
|
|
|
|
/// To arrive at the end of the scrolling container, the object's origin has to cover
|
|
|
|
|
|
/// <code>1000 + 100 = 1100px</code>
|
|
|
|
|
|
/// so that the edge starts at the end of the scrolling container.
|
|
|
|
|
|
/// One scroll length of 1000px covers 5000ms of time, so the time required to cover 1100px is equal to
|
|
|
|
|
|
/// <code>5000 * (1100 / 1000) = 5500ms,</code>
|
|
|
|
|
|
/// and therefore the object should start being visible at
|
|
|
|
|
|
/// <code>7000 - 5500 = 1500ms.</code>
|
|
|
|
|
|
/// </example>
|
|
|
|
|
|
/// <param name="originTime">The time point at which the object origin should enter the time range.</param>
|
|
|
|
|
|
/// <param name="offset">The spatial distance between the object's edge and its origin along the scrolling axis.</param>
|
2018-10-30 09:33:24 +00:00
|
|
|
|
/// <param name="timeRange">The amount of visible time.</param>
|
Fix lifetime calculation in overlapping algorithm
Changes to lifetime calculation in scrolling rulesets introduced in
#7367, which aimed to account for the distance between hit objects'
origin and its edge entering the scrolling area, fixed some issues with
hitobjects appearing abruptly, but also regressed some other scenarios.
Upon investigation, the regression was localised to the overlapping
scroll algorithm. The reason for this was two-fold:
* The previous code used TimeAt() to calculate the time of travel from
the hit object's edge to its origin. For other algorithms, that time
can be accurately reconstructed, because they don't have periods of
time where there are multiple hit objects scrolling at different
velocities.
That invariant does not hold for the overlapping algorithm, therefore
it is possible for different values to be technically correct for
TimeAt(). However, the only value that matters for the adjustment
is the one that's indicated by the control point that applies to the
hit object origin, which can be uniquely identified.
* Additionally, the offset returned (even if correct) was applied
externally to the hit object's start time and passed to
GetDisplayStartTime(). In the overlapping algorithm, the choice of
control point used in GetDisplayStartTime() is important, since
the value of the speed multiplier is read within.
Externally rewinding the hit object's start time meant that in some
cases the speed multiplier of the *previous* control point is applied,
which led to hit objects appearing too late if the scrolling rate
decreased.
Because of the above, modify GetDisplayStartTime() to take the offset
into account in all algorithms, and apply the adjustment correctly
inside of them. The constant and sequential algorithms needed no
adjustment from the previous logic, since:
* the constant algorithm disregarded control points, and
* the sequential algorithm would effectively rewind to time = 0,
calculate the absolute distance from time = 0 to the hit object start,
apply the origin offset *to the absolute distance*, and then convert
back to time, applying all control points in sequence. Due to this
it was impossible for control points to get mixed up while
calculating.
As for the overlapping algorithm, the high-level logic is as follows:
* The distance that the origin has to travel is the length of the scroll
plus the distance from the origin to the object edge.
* The above distance divided by the scroll length gives the relative
scroll lengths that the object has to travel.
* As one relative scroll length takes one time range, the relative
travel length multiplied by the time range gives the absolute travel
time of the object origin.
* Finally, the control point multiplier applicable at origin time is
applied to the whole travel time.
Correctness of the above is demonstrated by visual tests added before
and headless unit tests of the algorithms themselves. The sequential
scroll algorithm was not covered by unit tests, and remains uncovered
due to floating-point inaccuracies that should be addressed separately.
2020-02-06 21:46:31 +00:00
|
|
|
|
/// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param>
|
|
|
|
|
|
/// <returns>The time at which the object should enter the time range.</returns>
|
|
|
|
|
|
double GetDisplayStartTime(double originTime, float offset, double timeRange, float scrollLength);
|
2018-10-30 08:31:43 +00:00
|
|
|
|
|
2018-10-30 09:14:11 +00:00
|
|
|
|
/// <summary>
|
|
|
|
|
|
/// Computes the spatial length within a start and end time.
|
|
|
|
|
|
/// </summary>
|
|
|
|
|
|
/// <param name="startTime">The start time.</param>
|
|
|
|
|
|
/// <param name="endTime">The end time.</param>
|
2018-10-30 09:33:24 +00:00
|
|
|
|
/// <param name="timeRange">The amount of visible time.</param>
|
2019-11-17 12:49:36 +00:00
|
|
|
|
/// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param>
|
2018-10-30 09:14:11 +00:00
|
|
|
|
/// <returns>The absolute spatial length.</returns>
|
2018-10-30 09:33:24 +00:00
|
|
|
|
float GetLength(double startTime, double endTime, double timeRange, float scrollLength);
|
2018-10-30 08:31:43 +00:00
|
|
|
|
|
2018-10-30 09:14:11 +00:00
|
|
|
|
/// <summary>
|
|
|
|
|
|
/// Given the current time, computes the spatial position of a point in time.
|
|
|
|
|
|
/// </summary>
|
|
|
|
|
|
/// <param name="time">The time to compute the spatial position of.</param>
|
|
|
|
|
|
/// <param name="currentTime">The current time.</param>
|
2018-10-30 09:33:24 +00:00
|
|
|
|
/// <param name="timeRange">The amount of visible time.</param>
|
2019-11-17 12:49:36 +00:00
|
|
|
|
/// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param>
|
2018-10-30 09:14:11 +00:00
|
|
|
|
/// <returns>The absolute spatial position.</returns>
|
2018-10-30 09:33:24 +00:00
|
|
|
|
float PositionAt(double time, double currentTime, double timeRange, float scrollLength);
|
|
|
|
|
|
|
2018-11-09 10:55:48 +00:00
|
|
|
|
/// <summary>
|
|
|
|
|
|
/// Computes the time which brings a point to a provided spatial position given the current time.
|
|
|
|
|
|
/// </summary>
|
|
|
|
|
|
/// <param name="position">The absolute spatial position.</param>
|
|
|
|
|
|
/// <param name="currentTime">The current time.</param>
|
|
|
|
|
|
/// <param name="timeRange">The amount of visible time.</param>
|
2019-11-17 12:49:36 +00:00
|
|
|
|
/// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param>
|
2019-04-25 08:36:17 +00:00
|
|
|
|
/// <returns>The time at which <see cref="PositionAt(double,double,double,float)"/> == <paramref name="position"/>.</returns>
|
2018-11-09 10:55:48 +00:00
|
|
|
|
double TimeAt(float position, double currentTime, double timeRange, float scrollLength);
|
|
|
|
|
|
|
2018-10-30 09:33:24 +00:00
|
|
|
|
/// <summary>
|
2018-11-02 10:51:34 +00:00
|
|
|
|
/// Resets this <see cref="IScrollAlgorithm"/> to a default state.
|
2018-10-30 09:33:24 +00:00
|
|
|
|
/// </summary>
|
|
|
|
|
|
void Reset();
|
2018-01-07 03:47:09 +00:00
|
|
|
|
}
|
|
|
|
|
|
}
|
