// 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. namespace osu.Game.Rulesets.UI.Scrolling.Algorithms { public interface IScrollAlgorithm { /// <summary> /// 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. /// </summary> /// <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> /// <param name="timeRange">The amount of visible time.</param> /// <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); /// <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> /// <param name="timeRange">The amount of visible time.</param> /// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param> /// <returns>The absolute spatial length.</returns> float GetLength(double startTime, double endTime, double timeRange, float scrollLength); /// <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> /// <param name="timeRange">The amount of visible time.</param> /// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param> /// <param name="originTime">The time to be used for control point lookups (ie. the parent's start time for nested hit objects).</param> /// <returns>The absolute spatial position.</returns> float PositionAt(double time, double currentTime, double timeRange, float scrollLength, double? originTime = null); /// <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> /// <param name="scrollLength">The absolute spatial length through <paramref name="timeRange"/>.</param> /// <returns>The time at which <see cref="PositionAt(double,double,double,float, double?)"/> == <paramref name="position"/>.</returns> double TimeAt(float position, double currentTime, double timeRange, float scrollLength); /// <summary> /// Resets this <see cref="IScrollAlgorithm"/> to a default state. /// </summary> void Reset(); } }