Merge branch 'gcc-abstraction' into multiplayer-spectator-screen

osu.Game/Screens/Play/GameplayClockContainer.cs

@@ -10,26 +10,36 @@ using osu.Framework.Timing;
 
 namespace osu.Game.Screens.Play
 {
+    /// <summary>
+    /// Encapsulates gameplay timing logic and provides a <see cref="GameplayClock"/> via DI for gameplay components to use.
+    /// </summary>
     public abstract class GameplayClockContainer : Container, IAdjustableClock
     {
         /// <summary>
-        /// The final clock which is exposed to underlying components.
+        /// The final clock which is exposed to gameplay components.
         /// </summary>
         public GameplayClock GameplayClock { get; private set; }
 
+        /// <summary>
+        /// Whether gameplay is paused.
+        /// </summary>
         public readonly BindableBool IsPaused = new BindableBool();
 
         /// <summary>
-        /// The decoupled clock used for gameplay. Should be used for seeks and clock control.
+        /// The adjustable source clock used for gameplay. Should be used for seeks and clock control.
         /// </summary>
-        protected readonly DecoupleableInterpolatingFramedClock AdjustableClock;
+        protected readonly DecoupleableInterpolatingFramedClock AdjustableSource;
 
+        /// <summary>
+        /// Creates a new <see cref="GameplayClockContainer"/>.
+        /// </summary>
+        /// <param name="sourceClock">The source <see cref="IClock"/> used for timing.</param>
         protected GameplayClockContainer(IClock sourceClock)
         {
             RelativeSizeAxes = Axes.Both;
 
-            AdjustableClock = new DecoupleableInterpolatingFramedClock { IsCoupled = false };
+            AdjustableSource = new DecoupleableInterpolatingFramedClock { IsCoupled = false };
-            AdjustableClock.ChangeSource(sourceClock);
+            AdjustableSource.ChangeSource(sourceClock);
 
             IsPaused.BindValueChanged(OnIsPausedChanged);
         }
@@ -38,21 +48,24 @@ namespace osu.Game.Screens.Play
         {
             var dependencies = new DependencyContainer(base.CreateChildDependencies(parent));
 
-            dependencies.CacheAs(GameplayClock = CreateGameplayClock(AdjustableClock));
+            dependencies.CacheAs(GameplayClock = CreateGameplayClock(AdjustableSource));
             GameplayClock.IsPaused.BindTo(IsPaused);
 
             return dependencies;
         }
 
+        /// <summary>
+        /// Starts gameplay.
+        /// </summary>
         public virtual void Start()
         {
-            if (!AdjustableClock.IsRunning)
+            if (!AdjustableSource.IsRunning)
             {
                 // Seeking the decoupled clock to its current time ensures that its source clock will be seeked to the same time
                 // This accounts for the clock source potentially taking time to enter a completely stopped state
                 Seek(GameplayClock.CurrentTime);
 
-                AdjustableClock.Start();
+                AdjustableSource.Start();
             }
 
             IsPaused.Value = false;
@@ -60,19 +73,22 @@ namespace osu.Game.Screens.Play
 
         /// <summary>
         /// Seek to a specific time in gameplay.
-        /// <remarks>
-        /// Adjusts for any offsets which have been applied (so the seek may not be the expected point in time on the underlying audio track).
-        /// </remarks>
         /// </summary>
         /// <param name="time">The destination time to seek to.</param>
-        public virtual void Seek(double time) => AdjustableClock.Seek(time);
+        public virtual void Seek(double time) => AdjustableSource.Seek(time);
 
+        /// <summary>
+        /// Stops gameplay.
+        /// </summary>
         public virtual void Stop() => IsPaused.Value = true;
 
+        /// <summary>
+        /// Restarts gameplay.
+        /// </summary>
         public virtual void Restart()
         {
-            AdjustableClock.Seek(0);
+            AdjustableSource.Seek(0);
-            AdjustableClock.Stop();
+            AdjustableSource.Stop();
 
             if (!IsPaused.Value)
                 Start();
@@ -86,8 +102,26 @@ namespace osu.Game.Screens.Play
             base.Update();
         }
 
-        protected abstract void OnIsPausedChanged(ValueChangedEvent<bool> isPaused);
+        /// <summary>
+        /// Invoked when the value of <see cref="IsPaused"/> is changed to start or stop the <see cref="AdjustableSource"/> clock.
+        /// </summary>
+        /// <param name="isPaused">Whether the clock should now be paused.</param>
+        protected virtual void OnIsPausedChanged(ValueChangedEvent<bool> isPaused)
+        {
+            if (isPaused.NewValue)
+                AdjustableSource.Stop();
+            else
+                AdjustableSource.Start();
+        }
 
+        /// <summary>
+        /// Creates the final <see cref="GameplayClock"/> which is exposed via DI to be used by gameplay components.
+        /// </summary>
+        /// <remarks>
+        /// Any intermediate clocks such as platform offsets should be applied here.
+        /// </remarks>
+        /// <param name="source">The <see cref="IFrameBasedClock"/> providing the source time.</param>
+        /// <returns>The final <see cref="GameplayClock"/>.</returns>
         protected abstract GameplayClock CreateGameplayClock(IFrameBasedClock source);
 
         #region IAdjustableClock

osu.Game/Screens/Play/MasterGameplayClockContainer.cs

@@ -16,6 +16,16 @@ using osu.Game.Configuration;
 
 namespace osu.Game.Screens.Play
 {
+    /// <summary>
+    /// A <see cref="GameplayClockContainer"/> which uses a <see cref="WorkingBeatmap"/> as a source.
+    /// <para>
+    /// This is the most complete <see cref="GameplayClockContainer"/> which takes into account all user and platform offsets,
+    /// and provides implementations for user actions such as skipping or adjusting playback rates that may occur during gameplay.
+    /// </para>
+    /// </summary>
+    /// <remarks>
+    /// This is intended to be used as a single controller for gameplay, or as a reference source for other <see cref="GameplayClockContainer"/>s.
+    /// </remarks>
     public class MasterGameplayClockContainer : GameplayClockContainer
     {
         /// <summary>
@@ -23,7 +33,7 @@ namespace osu.Game.Screens.Play
         /// </summary>
         public const double MINIMUM_SKIP_TIME = 1000;
 
-        protected Track Track => (Track)AdjustableClock.Source;
+        protected Track Track => (Track)AdjustableSource.Source;
 
         public readonly BindableNumber<double> UserPlaybackRate = new BindableDouble(1)
         {
@@ -84,17 +94,25 @@ namespace osu.Game.Screens.Play
 
             Seek(startTime);
 
-            AdjustableClock.ProcessFrame();
+            AdjustableSource.ProcessFrame();
         }
 
         protected override void OnIsPausedChanged(ValueChangedEvent<bool> isPaused)
         {
+            // The source is stopped by a frequency fade first.
             if (isPaused.NewValue)
-                this.TransformBindableTo(pauseFreqAdjust, 0, 200, Easing.Out).OnComplete(_ => AdjustableClock.Stop());
+                this.TransformBindableTo(pauseFreqAdjust, 0, 200, Easing.Out).OnComplete(_ => AdjustableSource.Stop());
             else
                 this.TransformBindableTo(pauseFreqAdjust, 1, 200, Easing.In);
         }
 
+        /// <summary>
+        /// Seek to a specific time in gameplay.
+        /// </summary>
+        /// <remarks>
+        /// Adjusts for any offsets which have been applied (so the seek may not be the expected point in time on the underlying audio track).
+        /// </remarks>
+        /// <param name="time">The destination time to seek to.</param>
         public override void Seek(double time)
         {
             // remove the offset component here because most of the time we want the seek to be aligned to gameplay, not the audio track.
@@ -128,8 +146,6 @@ namespace osu.Game.Screens.Play
             Seek(skipTarget);
         }
 
-        protected override IFrameBasedClock ClockToProcess => userOffsetClock;
-
         protected override GameplayClock CreateGameplayClock(IFrameBasedClock source)
         {
             // Lazer's audio timings in general doesn't match stable. This is the result of user testing, albeit limited.
@@ -148,7 +164,7 @@ namespace osu.Game.Screens.Play
         public void StopUsingBeatmapClock()
         {
             removeSourceClockAdjustments();
-            AdjustableClock.ChangeSource(new TrackVirtual(beatmap.Track.Length));
+            AdjustableSource.ChangeSource(new TrackVirtual(beatmap.Track.Length));
         }
 
         private bool speedAdjustmentsApplied;