add render-step events

Author: Pathoschild

docs/release-notes.md

@@ -11,6 +11,7 @@
 
 * For mod authors:
   * Updated to .NET 6.
+  * Added `RenderingStep` and `RenderedStep` events, which let you handle a specific step in the game's render cycle.
   * Removed all deprecated APIs.
   * SMAPI no longer intercepts output written to the console. Mods which directly access `Console` will be listed under mod warnings.
 

src/SMAPI/Events/IDisplayEvents.cs

@@ -9,6 +9,12 @@ public interface IDisplayEvents
         /// <summary>Raised after a game menu is opened, closed, or replaced.</summary>
         event EventHandler<MenuChangedEventArgs> MenuChanged;
 
+        /// <summary>Raised before the game draws a specific step in the rendering cycle.</summary>
+        event EventHandler<RenderingStepEventArgs> RenderingStep;
+
+        /// <summary>Raised after the game draws a specific step in the rendering cycle.</summary>
+        event EventHandler<RenderedStepEventArgs> RenderedStep;
+
         /// <summary>Raised before the game draws anything to the screen in a draw tick, as soon as the sprite batch is opened. The sprite batch may be closed and reopened multiple times after this event is called, but it's only raised once per draw tick. This event isn't useful for drawing to the screen, since the game will draw over it.</summary>
         event EventHandler<RenderingEventArgs> Rendering;
 

src/SMAPI/Events/RenderedStepEventArgs.cs

@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Xna.Framework.Graphics;
+using StardewValley;
+using StardewValley.Mods;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IDisplayEvents.RenderedStep"/> event.</summary>
+    public class RenderedStepEventArgs : EventArgs
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>The cached instance for each render step.</summary>
+        private static readonly Dictionary<RenderSteps, RenderedStepEventArgs> Instances = new();
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The current step in the render cycle.</summary>
+        public RenderSteps Step { get; }
+
+        /// <summary>The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch.</summary>
+        public SpriteBatch SpriteBatch => Game1.spriteBatch;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="step">The current step in the render cycle.</param>
+        public RenderedStepEventArgs(RenderSteps step)
+        {
+            this.Step = step;
+        }
+
+        /// <summary>Get an instance for a render step.</summary>
+        /// <param name="step">The current step in the render cycle.</param>
+        internal static RenderedStepEventArgs Instance(RenderSteps step)
+        {
+            if (!RenderedStepEventArgs.Instances.TryGetValue(step, out RenderedStepEventArgs instance))
+                RenderedStepEventArgs.Instances[step] = instance = new(step);
+
+            return instance;
+        }
+    }
+}

src/SMAPI/Events/RenderingStepEventArgs.cs

@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Xna.Framework.Graphics;
+using StardewValley;
+using StardewValley.Mods;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for an <see cref="IDisplayEvents.RenderingStep"/> event.</summary>
+    public class RenderingStepEventArgs : EventArgs
+    {
+        /*********
+        ** Fields
+        *********/
+        /// <summary>The cached instance for each render step.</summary>
+        private static readonly Dictionary<RenderSteps, RenderingStepEventArgs> Instances = new();
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The current step in the render cycle.</summary>
+        public RenderSteps Step { get; }
+
+        /// <summary>The sprite batch being drawn. Add anything you want to appear on-screen to this sprite batch.</summary>
+        public SpriteBatch SpriteBatch => Game1.spriteBatch;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="step">The current step in the render cycle.</param>
+        public RenderingStepEventArgs(RenderSteps step)
+        {
+            this.Step = step;
+        }
+
+        /// <summary>Get an instance for a render step.</summary>
+        /// <param name="step">The current step in the render cycle.</param>
+        internal static RenderingStepEventArgs Instance(RenderSteps step)
+        {
+            if (!RenderingStepEventArgs.Instances.TryGetValue(step, out RenderingStepEventArgs instance))
+                RenderingStepEventArgs.Instances[step] = instance = new(step);
+
+            return instance;
+        }
+    }
+}

src/SMAPI/Framework/Events/EventManager.cs

@@ -36,6 +36,12 @@ internal class EventManager
         /// <inheritdoc cref="IDisplayEvents.Rendered" />
         public readonly ManagedEvent<RenderedEventArgs> Rendered;
 
+        /// <inheritdoc cref="IDisplayEvents.RenderingStep" />
+        public readonly ManagedEvent<RenderingStepEventArgs> RenderingStep;
+
+        /// <inheritdoc cref="IDisplayEvents.RenderedStep" />
+        public readonly ManagedEvent<RenderedStepEventArgs> RenderedStep;
+
         /// <inheritdoc cref="IDisplayEvents.RenderingWorld" />
         public readonly ManagedEvent<RenderingWorldEventArgs> RenderingWorld;
 
@@ -212,6 +218,8 @@ ManagedEvent<TEventArgs> ManageEventOf<TEventArgs>(string typeName, string event
             this.MenuChanged = ManageEventOf<MenuChangedEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.MenuChanged));
             this.Rendering = ManageEventOf<RenderingEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.Rendering));
             this.Rendered = ManageEventOf<RenderedEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.Rendered));
+            this.RenderingStep = ManageEventOf<RenderingStepEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.RenderingStep));
+            this.RenderedStep = ManageEventOf<RenderedStepEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.RenderedStep));
             this.RenderingWorld = ManageEventOf<RenderingWorldEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.RenderingWorld));
             this.RenderedWorld = ManageEventOf<RenderedWorldEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.RenderedWorld));
             this.RenderingActiveMenu = ManageEventOf<RenderingActiveMenuEventArgs>(nameof(IModEvents.Display), nameof(IDisplayEvents.RenderingActiveMenu));

src/SMAPI/Framework/Events/ModDisplayEvents.cs

@@ -16,6 +16,20 @@ public event EventHandler<MenuChangedEventArgs> MenuChanged
             remove => this.EventManager.MenuChanged.Remove(value);
         }
 
+        /// <inheritdoc />
+        public event EventHandler<RenderingStepEventArgs> RenderingStep
+        {
+            add => this.EventManager.RenderingStep.Add(value, this.Mod);
+            remove => this.EventManager.RenderingStep.Remove(value);
+        }
+
+        /// <inheritdoc />
+        public event EventHandler<RenderedStepEventArgs> RenderedStep
+        {
+            add => this.EventManager.RenderedStep.Add(value, this.Mod);
+            remove => this.EventManager.RenderedStep.Remove(value);
+        }
+
         /// <inheritdoc />
         public event EventHandler<RenderingEventArgs> Rendering
         {

src/SMAPI/Framework/SCore.cs

@@ -1222,6 +1222,10 @@ private void OnRenderingStep(RenderSteps step, SpriteBatch spriteBatch, RenderTa
                     this.RaiseRenderEvent(events.RenderingHud, spriteBatch, renderTarget);
                     break;
             }
+
+            // raise generic rendering stage event
+            if (events.RenderingStep.HasListeners)
+                this.RaiseRenderEvent(events.RenderingStep, spriteBatch, renderTarget, RenderingStepEventArgs.Instance(step));
         }
 
         /// <summary>Raised when the game finishes a render step in the draw loop.</summary>
@@ -1246,6 +1250,10 @@ private void OnRenderedStep(RenderSteps step, SpriteBatch spriteBatch, RenderTar
                     this.RaiseRenderEvent(events.RenderedHud, spriteBatch, renderTarget);
                     break;
             }
+
+            // raise generic rendering stage event
+            if (events.RenderedStep.HasListeners)
+                this.RaiseRenderEvent(events.RenderedStep, spriteBatch, renderTarget, RenderedStepEventArgs.Instance(step));
         }
 
         /// <summary>Raised after an instance finishes a draw loop.</summary>
@@ -1262,6 +1270,18 @@ private void OnRendered(RenderTarget2D renderTarget)
         /// <param name="renderTarget">The render target being drawn to the screen.</param>
         private void RaiseRenderEvent<TEventArgs>(ManagedEvent<TEventArgs> @event, SpriteBatch spriteBatch, RenderTarget2D renderTarget)
             where TEventArgs : EventArgs, new()
+        {
+            this.RaiseRenderEvent(@event, spriteBatch, renderTarget, Singleton<TEventArgs>.Instance);
+        }
+
+        /// <summary>Raise a rendering/rendered event, temporarily opening the given sprite batch if needed to let mods draw to it.</summary>
+        /// <typeparam name="TEventArgs">The event args type to construct.</typeparam>
+        /// <param name="event">The event to raise.</param>
+        /// <param name="spriteBatch">The sprite batch being drawn to the screen.</param>
+        /// <param name="renderTarget">The render target being drawn to the screen.</param>
+        /// <param name="eventArgs">The event arguments to pass to the event.</param>
+        private void RaiseRenderEvent<TEventArgs>(ManagedEvent<TEventArgs> @event, SpriteBatch spriteBatch, RenderTarget2D renderTarget, TEventArgs eventArgs)
+            where TEventArgs : EventArgs
         {
             if (!@event.HasListeners)
                 return;
@@ -1287,7 +1307,7 @@ private void RaiseRenderEvent<TEventArgs>(ManagedEvent<TEventArgs> @event, Sprit
                         Game1.SetRenderTarget(renderTarget);
                 }
 
-                @event.RaiseEmpty();
+                @event.Raise(eventArgs);
             }
             finally
             {