From 32c2f251967a1ecc9d7370a7497d06fcb8ad7eb8 Mon Sep 17 00:00:00 2001 From: Harrison Deng Date: Sun, 13 Jan 2019 23:23:03 -0600 Subject: [PATCH] documentation --- .../ScreenSystem/ITransition.cs | 8 +-- .../ScreenSystem/LoadingScreen.cs | 6 +- RecrownedAthenaeum/ScreenSystem/Screen.cs | 44 ++++++++++---- .../ScreenSystem/ScreenManager.cs | 58 +++++++++++++++---- RecrownedAthenaeum/UI/Modular/UIModule.cs | 29 ++++++++-- .../UI/Modular/UIModuleGroup.cs | 8 +++ 6 files changed, 117 insertions(+), 36 deletions(-) diff --git a/RecrownedAthenaeum/ScreenSystem/ITransition.cs b/RecrownedAthenaeum/ScreenSystem/ITransition.cs index dd66582..7ccf295 100644 --- a/RecrownedAthenaeum/ScreenSystem/ITransition.cs +++ b/RecrownedAthenaeum/ScreenSystem/ITransition.cs @@ -15,18 +15,18 @@ namespace RecrownedAthenaeum.ScreenSystem /// Called every frame if the state of the screen this transition is placed upon is in the enter transition phase. /// /// The time passed in seconds since the last frame. - /// Whether or not if all assets have been loaded by the . + /// Whether or not this transition is waiting on something. Usually the . /// The frame being rendered by the screen as it exits. This can be null. /// If this returns true, then it is considered that this transition is complete. - bool EnteringTransition(double delta, bool assetsLoaded); + bool EnteringTransition(double delta, bool waiting); /// /// Called every frame if the state of the screen this transition is placed upon is in the exit phase. /// /// The time passed in seconds since the last frame. - /// Whether or not if all assets have been loaded by the . + /// Whether or not this transition is waiting on something. Usually the . /// If this returns true, then it is considered that this transition is complete. - bool ExitingTransition(double delta, bool assetsLoaded); + bool ExitingTransition(double delta, bool waiting); /// /// Called once every frame while transition is active. Meant to draw transition. diff --git a/RecrownedAthenaeum/ScreenSystem/LoadingScreen.cs b/RecrownedAthenaeum/ScreenSystem/LoadingScreen.cs index faf6e89..7ccfb36 100644 --- a/RecrownedAthenaeum/ScreenSystem/LoadingScreen.cs +++ b/RecrownedAthenaeum/ScreenSystem/LoadingScreen.cs @@ -69,14 +69,14 @@ namespace RecrownedAthenaeum.ScreenSystem } - public bool EnteringTransition(double delta, bool assetsLoaded) + public bool EnteringTransition(double delta, bool waiting) { float deltaf = (float)delta; if (rotate) { DoRotate(deltaf); } - if (assetsLoaded) + if (waiting) { if (progR < 254 || progG < 254 || progB < 254) { @@ -106,7 +106,7 @@ namespace RecrownedAthenaeum.ScreenSystem return false; } - public bool ExitingTransition(double delta, bool assetsLoaded) + public bool ExitingTransition(double delta, bool waiting) { float deltaf = (float)delta; if (rotate) diff --git a/RecrownedAthenaeum/ScreenSystem/Screen.cs b/RecrownedAthenaeum/ScreenSystem/Screen.cs index d9ed656..286a635 100644 --- a/RecrownedAthenaeum/ScreenSystem/Screen.cs +++ b/RecrownedAthenaeum/ScreenSystem/Screen.cs @@ -26,9 +26,6 @@ namespace RecrownedAthenaeum.ScreenSystem /// /// Called only once after initialization to give required parameters. /// - /// - /// - /// public virtual void Initiate(GraphicsDevice graphicsDevice, Rectangle screenSize, Camera2D camera) { this.Camera = camera; @@ -37,11 +34,19 @@ namespace RecrownedAthenaeum.ScreenSystem Initiated = true; } + /// + /// Called to update the screen. + /// + /// Game time information. public virtual void Update(GameTime gameTime) { } + /// + /// Called to draw this screen. + /// + /// SpriteBatch to use. public virtual void Draw(SpriteBatch spriteBatch) { foreach (ITransition transition in Transitions) @@ -51,33 +56,33 @@ namespace RecrownedAthenaeum.ScreenSystem } /// - /// Updates the transition. + /// Updates the transition based on the current state of the screen. /// /// Time passed since last frame in seconds. - /// If waiting on assets. + /// If the this transition should wait. /// The previous screen's frame. May be null. /// Only returns true if exit transition is complete. Returns false otherwise. - public bool UpdateTransition(double delta, bool assetsLoaded) + public bool UpdateTransition(double delta, bool waiting) { switch (State) { case ScreenState.EnterTransition: - EnteringTransition(delta, assetsLoaded); + EnteringTransition(delta, waiting); break; case ScreenState.ExitTransition: - return ExitingTransition(delta, assetsLoaded); + return ExitingTransition(delta, waiting); } return false; } - private void EnteringTransition(double delta, bool assetsLoaded) + private void EnteringTransition(double delta, bool waiting) { bool complete = true; for (int transitionID = 0; transitionID < Transitions.Count; transitionID++) { ITransition transition = Transitions[transitionID]; - if (!transition.EnteringTransition(delta, assetsLoaded)) + if (!transition.EnteringTransition(delta, waiting)) { complete = false; } @@ -88,12 +93,12 @@ namespace RecrownedAthenaeum.ScreenSystem } } - private bool ExitingTransition(double delta, bool assetsLoaded) + private bool ExitingTransition(double delta, bool waiting) { bool complete = true; foreach (ITransition transition in Transitions) { - if (!transition.ExitingTransition(delta, assetsLoaded)) + if (!transition.ExitingTransition(delta, waiting)) { complete = false; } @@ -113,11 +118,18 @@ namespace RecrownedAthenaeum.ScreenSystem } } + /// + /// Called when this screen is no longer the displayed screen. + /// public virtual void Hide() { } + /// + /// Called whenever the status of assets changes from being loaded to unloaded or unloaded to loaded. + /// + /// True for loaded, false for unloaded. public virtual void AssetLoadStateChange(bool state) { @@ -125,12 +137,20 @@ namespace RecrownedAthenaeum.ScreenSystem public ScreenState State { get; private set; } + /// + /// Call this to begin exit transition. + /// + /// Whether or not to use a render target for the next screen to use. public void StartExitTransition(bool UseRenderTargetForExitTransition = false) { this.UseRenderTargetForExitTransition = UseRenderTargetForExitTransition; State = ScreenState.ExitTransition; } + /// + /// Called everytime the previous screen frame buffer updates. Used for transition purposes. + /// + /// The previous screen's render buffer. public virtual void UpdatePreviousScreenFrame(RenderTarget2D previousScreenFrame) { foreach (ITransition transition in Transitions) diff --git a/RecrownedAthenaeum/ScreenSystem/ScreenManager.cs b/RecrownedAthenaeum/ScreenSystem/ScreenManager.cs index e364053..8a95c82 100644 --- a/RecrownedAthenaeum/ScreenSystem/ScreenManager.cs +++ b/RecrownedAthenaeum/ScreenSystem/ScreenManager.cs @@ -6,19 +6,30 @@ using System.Diagnostics; namespace RecrownedAthenaeum.ScreenSystem { - public delegate void FirstScreenChange(Screen screen); + /// + /// Called when the first screen is being shown. + /// + /// The screen to show after the loading screen. + public delegate void ShowFirstScreen(Screen screen); public class ScreenManager : IDisposable { bool disposed = false; - public event FirstScreenChange RequireNextScreenEvent; + /// + /// Called when the first loading screen is done, and needs to show the landing screen. + /// + public event ShowFirstScreen ShowFirstScreenEvent; private GraphicsDeviceManager graphics; private Screen previousScreen; private RenderTarget2D previousScreenRenderTarget; private Screen currentScreen; private Camera2D camera; private bool firstScreenChangeComplete; + private bool resizing; + /// + /// Currently displayed screen. + /// public Screen Screen { get @@ -46,25 +57,35 @@ namespace RecrownedAthenaeum.ScreenSystem } } + /// + /// Creates a screen manager that helps manage multiple screens and their transitions. + /// + /// The graphics device manager to be used. + /// The camera to be used to perform the correct translations and transformations. public ScreenManager(GraphicsDeviceManager graphicsDeviceManager, Camera2D camera) { this.graphics = graphicsDeviceManager; this.camera = camera; } - public void UpdateCurrentScreen(GameTime gameTime, bool assetsDone) + /// + /// Updates the screens. Should be called once every frame. + /// + /// Contains the time that has passed from the last frame. + /// Whether or not there is something a transition should be waiting for. Usually used to wait for assets to complete loading. + public void UpdateCurrentScreen(GameTime gameTime, bool waiting) { switch (Screen.State) { case ScreenState.EnterTransition: if (previousScreen != null && previousScreen.UseRenderTargetForExitTransition) { - previousScreen.UpdateTransition(gameTime.ElapsedGameTime.TotalSeconds, assetsDone); + previousScreen.UpdateTransition(gameTime.ElapsedGameTime.TotalSeconds, waiting); } - Screen.UpdateTransition(gameTime.ElapsedGameTime.TotalSeconds, assetsDone); + Screen.UpdateTransition(gameTime.ElapsedGameTime.TotalSeconds, waiting); break; case ScreenState.ExitTransition: - if (Screen.UseRenderTargetForExitTransition || Screen.UpdateTransition(gameTime.ElapsedGameTime.TotalSeconds, assetsDone)) + if (Screen.UseRenderTargetForExitTransition || Screen.UpdateTransition(gameTime.ElapsedGameTime.TotalSeconds, waiting)) { if (!firstScreenChangeComplete) { @@ -91,6 +112,10 @@ namespace RecrownedAthenaeum.ScreenSystem Screen.Update(gameTime); } + /// + /// Renders screen into window. + /// + /// Uses this batch to render. public void DrawCurrentScreen(SpriteBatch spriteBatch) { graphics.GraphicsDevice.Clear(Screen.BackgroundColor); @@ -109,22 +134,33 @@ namespace RecrownedAthenaeum.ScreenSystem spriteBatch.End(); } + /// + /// Should be called when resize is occurring to change to a loading screen. + /// This will notify the screen of the status of the assets, change the screen to a loading screen, and dispose of the previous screen buffer. + /// + /// The loading screen to change to. public void Resize(LoadingScreen loadingScreen) { - Screen.AssetLoadStateChange(true); + if (resizing) throw new InvalidOperationException("Already resizing."); + resizing = true; + Screen.AssetLoadStateChange(false); Screen = loadingScreen; previousScreenRenderTarget.Dispose(); previousScreenRenderTarget = null; } - + + /// + /// Notifies all screen that assets have completed being loaded after a resize. + /// public void PostResize() { - Screen.AssetLoadStateChange(false); + if (!resizing) throw new InvalidOperationException("Was never resizing."); + Screen.AssetLoadStateChange(true); } - public void OnFirstScreenChange(Screen screen) + private void OnFirstScreenChange(Screen screen) { - RequireNextScreenEvent?.Invoke(screen); + ShowFirstScreenEvent?.Invoke(screen); } public void Dispose() diff --git a/RecrownedAthenaeum/UI/Modular/UIModule.cs b/RecrownedAthenaeum/UI/Modular/UIModule.cs index b5fe5fe..be6f88d 100644 --- a/RecrownedAthenaeum/UI/Modular/UIModule.cs +++ b/RecrownedAthenaeum/UI/Modular/UIModule.cs @@ -14,29 +14,46 @@ namespace RecrownedAthenaeum.UI.Modular public string Name; public Color color = Color.White; + /// + /// Called every frame to update this module. Calculations and movement should go here. + /// + /// Game time information. public virtual void Update(GameTime gameTime) { + } + /// + /// Called every frame to draw this module. Anything that needs to be drawn should go here. + /// + /// Batch used to draw. public virtual void Draw(SpriteBatch batch) { } - public Rectangle ConvertToParentCoordinates(Rectangle bounds) + /// + /// Converts the given rectangle to the coordinates of the parent. + /// + /// Rectangle to convert. + /// + public Rectangle ConvertToParentCoordinates(Rectangle rectangle) { if (Parent != null) { - Rectangle parentHitbox = Parent.ConvertToParentCoordinates(bounds); - int tX = bounds.X + parentHitbox.X; - int tY = bounds.Y + parentHitbox.Y; - return new Rectangle(tX, tY, bounds.Width, bounds.Height); + Rectangle parentHitbox = Parent.ConvertToParentCoordinates(rectangle); + int tX = rectangle.X + parentHitbox.X; + int tY = rectangle.Y + parentHitbox.Y; + return new Rectangle(tX, tY, rectangle.Width, rectangle.Height); } else { - return bounds; + return rectangle; } } + /// + /// Removes this module from the parent. + /// public void RemoveFromParent() { if (Parent == null) diff --git a/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs b/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs index 2609d92..84c5925 100644 --- a/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs +++ b/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs @@ -65,6 +65,10 @@ namespace RecrownedAthenaeum.UI.Modular } } + /// + /// Adds module(s) to this group. + /// + /// The module(s) to add. public void AddModule(params UIModule[] addModules) { foreach (UIModule module in addModules) @@ -78,6 +82,10 @@ namespace RecrownedAthenaeum.UI.Modular } } + /// + /// Removes given module from group. + /// + /// module to remove. public void RemoveModule(UIModule module) { module.Parent = null;