From 40c7772559ed8dbcd84aa9500d2985f6961e4ba7 Mon Sep 17 00:00:00 2001 From: Harrison Deng Date: Mon, 14 Jan 2019 00:34:35 -0600 Subject: [PATCH] documentation. --- .../RecrownedAthenaeum.Pipeline.csproj | 1 + RecrownedAthenaeum/Camera/Camera2D.cs | 34 ++++++++- .../ContentSystem/ContentManagerController.cs | 46 ++++++++---- .../ContentSystem/IContentPathModifier.cs | 3 + RecrownedAthenaeum/Input/IInputListener.cs | 13 ++++ RecrownedAthenaeum/RecrownedAthenaeum.csproj | 1 + .../Render/RectangleRenderer.cs | 46 ++++++++++-- RecrownedAthenaeum/UI/Book/Book.cs | 31 ++++++++ .../UI/Modular/Modules/Image.cs | 71 ++++++++++--------- .../UI/Modular/Modules/Interactive/Button.cs | 46 +++++++++++- RecrownedAthenaeum/UI/Modular/UIModule.cs | 22 ++++++ .../UI/Modular/UIModuleGroup.cs | 22 ++++++ .../Skin/Definitions/ButtonSkinDefinition.cs | 13 ++++ .../UI/Skin/Definitions/ISkinDefinition.cs | 6 ++ RecrownedAthenaeum/UI/Skin/Skin.cs | 16 +++++ 15 files changed, 315 insertions(+), 56 deletions(-) diff --git a/RecrownedAthenaeum.Pipeline/RecrownedAthenaeum.Pipeline.csproj b/RecrownedAthenaeum.Pipeline/RecrownedAthenaeum.Pipeline.csproj index 2691450..f3bf100 100644 --- a/RecrownedAthenaeum.Pipeline/RecrownedAthenaeum.Pipeline.csproj +++ b/RecrownedAthenaeum.Pipeline/RecrownedAthenaeum.Pipeline.csproj @@ -29,6 +29,7 @@ TRACE prompt 4 + bin\Release\RecrownedAthenaeum.Pipeline.xml diff --git a/RecrownedAthenaeum/Camera/Camera2D.cs b/RecrownedAthenaeum/Camera/Camera2D.cs index ea7d4e4..869340d 100644 --- a/RecrownedAthenaeum/Camera/Camera2D.cs +++ b/RecrownedAthenaeum/Camera/Camera2D.cs @@ -4,13 +4,32 @@ using System; namespace RecrownedAthenaeum.Camera { + /// + /// A virtual 2D camera. + /// public class Camera2D { + /// + /// Current zoom level. + /// public float Zoom; - public Vector2 Position; - public Matrix Matrix { get; private set; } - public GraphicsDevice graphicsDevice; + /// + /// Current position in the world. + /// + public Vector2 Position; + + /// + /// The matrix representing the zoom and position. + /// + public Matrix Matrix { get; private set; } + + private GraphicsDevice graphicsDevice; + + /// + /// Constructs 2D camera. + /// + /// The graphics device to use. public Camera2D(GraphicsDevice graphicsDevice) { this.graphicsDevice = graphicsDevice; @@ -19,6 +38,9 @@ namespace RecrownedAthenaeum.Camera Position.Y = this.graphicsDevice.Viewport.Height * 0.5f; } + /// + /// Applies any changes made to the properties of this camera and updates to new dimensions of viewport specified by the graphics device. + /// public void Update() { Rectangle bounds = graphicsDevice.Viewport.Bounds; @@ -28,6 +50,12 @@ namespace RecrownedAthenaeum.Camera Matrix.CreateTranslation(new Vector3(bounds.Width * 0.5f, bounds.Height * 0.5f, 0f)); } + /// + /// Lerps to the given position. + /// + /// The multiplier for difference in distance. + /// The target position to lerp to. + /// Time between this frame and the previous frame. public void LinearInterpolationToPosition(float alpha, Vector2 targetPosition, float delta) { if (alpha <= 0 && alpha > 1f) throw new ArgumentException("Alpha can't be greater than 1f, less than or equal to 0."); diff --git a/RecrownedAthenaeum/ContentSystem/ContentManagerController.cs b/RecrownedAthenaeum/ContentSystem/ContentManagerController.cs index 887b9d6..ab4bc01 100644 --- a/RecrownedAthenaeum/ContentSystem/ContentManagerController.cs +++ b/RecrownedAthenaeum/ContentSystem/ContentManagerController.cs @@ -6,16 +6,36 @@ using System.Threading; namespace RecrownedAthenaeum.ContentSystem { + /// + /// Wrapper for the content manager that helps with controlling it by adding automated multithreaded content loading. + /// public class ContentManagerController { Thread thread; readonly ContentManager contentManager; readonly Queue queue; Dictionary assets; + /// + /// Path modifiers to change the path in which the content manager looks to load a file. Used for better organizing things while not needing to type entire path. + /// public readonly Dictionary contentPathModifier; volatile float progress; volatile bool running; + /// + /// Whether or not the queue is empty and all content is loaded. + /// + public bool Done { get { return !running && queue.Count == 0; } } + + /// + /// The progress of the loading. 1 is complete while 0 is incomplete. + /// + public float Progress { get { return progress; } } + + /// + /// Wraps the . + /// + /// The manager to wrap. public ContentManagerController(ContentManager contentManager) { this.contentManager = contentManager; @@ -38,6 +58,12 @@ namespace RecrownedAthenaeum.ContentSystem Debug.WriteLine("Loaded asset: " + assetName); } + /// + /// Gets the requested asset. + /// + /// The type of the asset for an alternative way to cast. + /// The name of the asset. + /// The asset casted to the type given with T. public T Get(string assetName) { lock (queue) @@ -46,6 +72,12 @@ namespace RecrownedAthenaeum.ContentSystem } } + /// + /// Queues an asset to be loaded. + /// + /// The type of the asset to be queued. + /// Name of asset to look for. + /// Whether or not to use the path modifiers. public void Queue(string assetName, bool usePathModifier = true) where T : IDisposable { lock (queue) @@ -133,20 +165,6 @@ namespace RecrownedAthenaeum.ContentSystem } } - public bool Done - { - get - { - return !running && queue.Count == 0; - } - } - public float Progress - { - get - { - return progress; - } - } } } diff --git a/RecrownedAthenaeum/ContentSystem/IContentPathModifier.cs b/RecrownedAthenaeum/ContentSystem/IContentPathModifier.cs index fee8346..ad64344 100644 --- a/RecrownedAthenaeum/ContentSystem/IContentPathModifier.cs +++ b/RecrownedAthenaeum/ContentSystem/IContentPathModifier.cs @@ -1,5 +1,8 @@ namespace RecrownedAthenaeum.ContentSystem { + /// + /// Modifies the given path based on a name. Used to simplify long paths for the + /// public interface IContentPathModifier { /// diff --git a/RecrownedAthenaeum/Input/IInputListener.cs b/RecrownedAthenaeum/Input/IInputListener.cs index 46ba91b..3120599 100644 --- a/RecrownedAthenaeum/Input/IInputListener.cs +++ b/RecrownedAthenaeum/Input/IInputListener.cs @@ -2,10 +2,23 @@ namespace RecrownedAthenaeum.Input { + /// + /// Input listener for . + /// public interface IInputListener { + /// + /// Called when the state of the keyboard has changed. + /// + /// The new state. + /// True to continue calling other listeners. bool KeyboardStateChanged(KeyboardState state); + /// + /// Called when the state of the mouse has changed. + /// + /// The new state. + /// True to continue calling other listeners. bool MouseStateChanged(MouseState state); } } diff --git a/RecrownedAthenaeum/RecrownedAthenaeum.csproj b/RecrownedAthenaeum/RecrownedAthenaeum.csproj index ae8b9c6..c771a89 100644 --- a/RecrownedAthenaeum/RecrownedAthenaeum.csproj +++ b/RecrownedAthenaeum/RecrownedAthenaeum.csproj @@ -31,6 +31,7 @@ TRACE prompt 4 + bin\Release\RecrownedAthenaeum.xml diff --git a/RecrownedAthenaeum/Render/RectangleRenderer.cs b/RecrownedAthenaeum/Render/RectangleRenderer.cs index ebcbf3c..956f5b6 100644 --- a/RecrownedAthenaeum/Render/RectangleRenderer.cs +++ b/RecrownedAthenaeum/Render/RectangleRenderer.cs @@ -5,23 +5,42 @@ using System; namespace RecrownedAthenaeum.Render { + /// + /// Renders rectangles using the . + /// public class RectangleRenderer : IDisposable { + /// + /// The used. + /// public readonly PrimitiveBatch primitiveBatch; private bool disposed; private bool began; private bool filling; + /// + /// Creates a rectangle renderer with the given . + /// + /// public RectangleRenderer(PrimitiveBatch primitiveBatch) { this.primitiveBatch = primitiveBatch; } + /// + /// Creates a rectangle renderer. + /// + /// The graphics device used to create the + /// The camera containing the matrix to be used for the transformations. public RectangleRenderer(GraphicsDevice graphicsDevice, Camera2D camera) : this(new PrimitiveBatch(graphicsDevice, camera, 4)) { } + /// + /// Begins the render batch. + /// + /// Whether or not to fill the rectangle. public void Begin(bool filled) { filling = filled; @@ -31,6 +50,9 @@ namespace RecrownedAthenaeum.Render began = true; } + /// + /// Ends the batch. + /// public void End() { if (disposed) throw new ObjectDisposedException(GetType().Name); @@ -77,25 +99,39 @@ namespace RecrownedAthenaeum.Render } } + /// + /// Attempts to dispose of this object. + /// public void Dispose() { + if (disposed) throw new ObjectDisposedException(typeof(PrimitiveBatch).Name); Dispose(true); GC.SuppressFinalize(this); } - public void Dispose(bool disposing) + /// + /// An overridable of disposable. + /// + /// Only true when called by user code dispose. Destructor calling this results in false. + public virtual void Dispose(bool disposing) { + disposed = true; if (!disposed && disposing) { + disposed = true; if (primitiveBatch != null) { primitiveBatch.Dispose(); } } - else - { - if (disposed) throw new ObjectDisposedException(typeof(PrimitiveBatch).Name); - } + } + + /// + /// Destructor. + /// + ~RectangleRenderer () + { + Dispose(false); } } } diff --git a/RecrownedAthenaeum/UI/Book/Book.cs b/RecrownedAthenaeum/UI/Book/Book.cs index 105b54d..b14beb9 100644 --- a/RecrownedAthenaeum/UI/Book/Book.cs +++ b/RecrownedAthenaeum/UI/Book/Book.cs @@ -6,6 +6,9 @@ using System.Linq; namespace RecrownedAthenaeum.UI.Book { + /// + /// Contains the pages. + /// public class Book { Camera2D camera; @@ -25,6 +28,10 @@ namespace RecrownedAthenaeum.UI.Book this.dimensions = dimensions; } + /// + /// Draws the pages. + /// + /// Batch used to draw. public void Draw(SpriteBatch batch) { for (int pageIndex = 0; pageIndex < pages.Count; pageIndex++) @@ -34,6 +41,10 @@ namespace RecrownedAthenaeum.UI.Book } } + /// + /// Updates the book. + /// + /// Snapshot of information of the game time. public void Update(GameTime gameTime) { if (targetPage != null) @@ -57,6 +68,10 @@ namespace RecrownedAthenaeum.UI.Book } } + /// + /// Adds the page(s). + /// + /// The page(s) to add. public void AddPages(params Page[] pages) { foreach (Page page in pages) @@ -65,21 +80,37 @@ namespace RecrownedAthenaeum.UI.Book } } + /// + /// Removes the page. + /// + /// Page to remove. public void RemovePage(Page page) { RemovePage(page.Name); } + /// + /// Removes the page. + /// + /// Name of page to remove. public void RemovePage(string name) { pages.Remove(name); } + /// + /// Perform a step of linear interpolation to the given page. + /// + /// The page to lerp to. public void LerpToPage(Page page) { targetPage = page; } + /// + /// Goes to page instantly. + /// + /// Page to go to. public void GoToPage(Page page) { Rectangle targetBounds = page.bounds; diff --git a/RecrownedAthenaeum/UI/Modular/Modules/Image.cs b/RecrownedAthenaeum/UI/Modular/Modules/Image.cs index db477f3..4eae7f8 100644 --- a/RecrownedAthenaeum/UI/Modular/Modules/Image.cs +++ b/RecrownedAthenaeum/UI/Modular/Modules/Image.cs @@ -5,57 +5,64 @@ using System; namespace RecrownedAthenaeum.UI.Modular.Modules { + /// + /// Represents a texture with more information. + /// public class Image : UIModule, ISpecialDrawable { + /// + /// The rotation of the image. + /// public float rotation = 0f; + + /// + /// The texture to be rendered. + /// public Texture2D Texture { get; set; } - public float ScaleX - { - get - { - return (float)bounds.Width / Texture.Width; - } + + /// + /// Scale of of the X axis. + /// + public float ScaleX { get { return (float)bounds.Width / Texture.Width; } set { bounds.Width = (int)(Texture.Width * value); } } - set - { - bounds.Width = (int)(Texture.Width * value); - } - } + /// + /// Scale of the Y axis. + /// + public float ScaleY { get { return (float)bounds.Height / Texture.Height; } set { bounds.Height = (int)(Texture.Height * value); } } - public float ScaleY - { - get - { - return (float)bounds.Height / Texture.Height; - } - - set - { - bounds.Height = (int)(Texture.Height * value); - } - } - - public float Scale - { - set - { - bounds.Height = (int)(Texture.Height * value); - bounds.Width = (int)(Texture.Width * value); - } - } + /// + /// Overall scale. + /// + public float Scale { set { bounds.Height = (int)(Texture.Height * value); bounds.Width = (int)(Texture.Width * value); } } + /// + /// Constructs an image given a texture. + /// + /// Texture to use. public Image(Texture2D texture) { Texture = texture ?? throw new ArgumentException("Image requires a texture."); bounds = texture.Bounds; } + /// + /// Draws the image with default values. + /// + /// The batch to use. public override void Draw(SpriteBatch batch) { batch.Draw(Texture, bounds, null, color, rotation, origin, SpriteEffects.None, 0f); base.Draw(batch); } + /// + /// Draws the image with more options. + /// + /// Batch used. + /// Where to draw texture to. + /// The color tint to use. + /// Rotation of image. + /// Origin for the rotation. public void Draw(SpriteBatch spriteBatch, Rectangle destination, Color color, float rotation = 0, Vector2 origin = default(Vector2)) { this.color = color; diff --git a/RecrownedAthenaeum/UI/Modular/Modules/Interactive/Button.cs b/RecrownedAthenaeum/UI/Modular/Modules/Interactive/Button.cs index 138c103..77b8fa7 100644 --- a/RecrownedAthenaeum/UI/Modular/Modules/Interactive/Button.cs +++ b/RecrownedAthenaeum/UI/Modular/Modules/Interactive/Button.cs @@ -6,17 +6,40 @@ using RecrownedAthenaeum.UI.Skin.Definitions; namespace RecrownedAthenaeum.UI.Modular.Modules.Interactive { - public delegate bool Clicked(); + /// + /// Function to be called when button is clicked. + /// + public delegate void Clicked(); + /// + /// A very primitive button containing all the basic functions. + /// public class Button : UIModule { private ButtonSkinDefinition skinDefinition; private ISpecialDrawable downTexture, upTexture, highlightedTexture, disabledTexture; + /// + /// Click event listeners. + /// public event Clicked Listeners; private bool pressed; + /// + /// Whether or not this button should be currently disabled. + /// public bool disabled = false; + + /// + /// Whether or not this button is currently being hovered on. + /// public bool Highlighted { get; private set; } + /// + /// Constructs this button using s for the different states it could be in. + /// + /// Button being pressed. + /// Button not being pressed. + /// Disabled button. + /// Button being highlighted. public Button(ISpecialDrawable down, ISpecialDrawable up, ISpecialDrawable disabled = null, ISpecialDrawable selected = null) { this.downTexture = down; @@ -25,6 +48,11 @@ namespace RecrownedAthenaeum.UI.Modular.Modules.Interactive this.highlightedTexture = selected; } + /// + /// Constructs this button using the skin system. + /// + /// The skin containing the information of the textures and design to follow. + /// The name of the definition in the skin. Can be null to select the default. public Button(Skin.Skin skin, string definitionName = null) { this.skinDefinition = skin.ObtainDefinition(definitionName, GetType()); @@ -34,6 +62,10 @@ namespace RecrownedAthenaeum.UI.Modular.Modules.Interactive highlightedTexture = skin.textureAtlas[skinDefinition.selectedRegion]; } + /// + /// Draws the button. + /// + /// Batch used to draw the button. public override void Draw(SpriteBatch batch) { if (disabled) @@ -54,6 +86,11 @@ namespace RecrownedAthenaeum.UI.Modular.Modules.Interactive base.Draw(batch); } + /// + /// Called when the mouse changes state. + /// + /// The new state. + /// Whether or not to continue calling the next mouse change listener. public sealed override bool MouseStateChanged(MouseState state) { if (InputUtilities.MouseWithinBoundries(bounds)) @@ -81,12 +118,17 @@ namespace RecrownedAthenaeum.UI.Modular.Modules.Interactive return base.MouseStateChanged(state); } + /// + /// Called when the state of the keyboard changes. + /// + /// The new state. + /// Whether or not the next keyboard change listener should be called. public sealed override bool KeyboardStateChanged(KeyboardState state) { return base.KeyboardStateChanged(state); } - protected void OnClick() + internal void OnClick() { Listeners?.Invoke(); } diff --git a/RecrownedAthenaeum/UI/Modular/UIModule.cs b/RecrownedAthenaeum/UI/Modular/UIModule.cs index be6f88d..c9f9606 100644 --- a/RecrownedAthenaeum/UI/Modular/UIModule.cs +++ b/RecrownedAthenaeum/UI/Modular/UIModule.cs @@ -6,12 +6,34 @@ using System; namespace RecrownedAthenaeum.UI.Modular { + + /// + /// Module for UI layout. + /// public class UIModule : IInputListener { + /// + /// Bounds of this module. + /// public Rectangle bounds; + /// + /// Origin of this module. + /// public Vector2 origin; + + /// + /// The parent of this module. May be null. + /// public UIModuleGroup Parent; + + /// + /// Name of this module. For organizational/referencial purposes mostly. + /// public string Name; + + /// + /// The color tint of this module. + /// public Color color = Color.White; /// diff --git a/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs b/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs index 84c5925..f6506db 100644 --- a/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs +++ b/RecrownedAthenaeum/UI/Modular/UIModuleGroup.cs @@ -7,6 +7,10 @@ using RecrownedAthenaeum.Camera; namespace RecrownedAthenaeum.UI.Modular { + + /// + /// Contains a group of modules and has its own relative coordinate system. + /// public class UIModuleGroup : UIModule { List modules = new List(); @@ -24,6 +28,10 @@ namespace RecrownedAthenaeum.UI.Modular } } + /// + /// Draws this group of modules. + /// + /// Batch used to draw the group. public override void Draw(SpriteBatch batch) { if (scissorBounds != null) @@ -57,6 +65,10 @@ namespace RecrownedAthenaeum.UI.Modular } } + /// + /// Updates the group of modules. + /// + /// Game time used. public override void Update(GameTime gameTime) { foreach (UIModule module in modules) @@ -92,6 +104,11 @@ namespace RecrownedAthenaeum.UI.Modular modules.Remove(module); } + /// + /// Updates the keyboard state of the modules in this group. + /// + /// The new state. + /// Whether or not to continue updating the other listeners. public override bool KeyboardStateChanged(KeyboardState state) { foreach (UIModule module in modules) @@ -101,6 +118,11 @@ namespace RecrownedAthenaeum.UI.Modular return base.KeyboardStateChanged(state); } + /// + /// Updates the moues state of the modules in this group. + /// + /// The new state. + /// Whether or not to continue updating other listeners. public override bool MouseStateChanged(MouseState state) { foreach (UIModule module in modules) diff --git a/RecrownedAthenaeum/UI/Skin/Definitions/ButtonSkinDefinition.cs b/RecrownedAthenaeum/UI/Skin/Definitions/ButtonSkinDefinition.cs index 413098e..3e28474 100644 --- a/RecrownedAthenaeum/UI/Skin/Definitions/ButtonSkinDefinition.cs +++ b/RecrownedAthenaeum/UI/Skin/Definitions/ButtonSkinDefinition.cs @@ -3,11 +3,24 @@ using System; namespace RecrownedAthenaeum.UI.Skin.Definitions { + /// + /// Definition for a button. + /// public class ButtonSkinDefinition : ISkinDefinition { + /// + /// Names for the regions in the texture atlas respectively. + /// public string upRegion, downRegion, disabledRegion, selectedRegion; + + /// public Type UIModuleType { get { return typeof(Button); } } + /// + /// Constructs the definition with minimum requirements. + /// + /// Name of region specifying the texture shown for when the button is pressed down. + /// Name of region specifying the texture shown for when the button is not pressed. public ButtonSkinDefinition(string downRegion, string upRegion) { this.downRegion = downRegion; diff --git a/RecrownedAthenaeum/UI/Skin/Definitions/ISkinDefinition.cs b/RecrownedAthenaeum/UI/Skin/Definitions/ISkinDefinition.cs index db6506c..9b2aa26 100644 --- a/RecrownedAthenaeum/UI/Skin/Definitions/ISkinDefinition.cs +++ b/RecrownedAthenaeum/UI/Skin/Definitions/ISkinDefinition.cs @@ -2,8 +2,14 @@ namespace RecrownedAthenaeum.UI.Skin.Definitions { + /// + /// A definition for the skin system. + /// public interface ISkinDefinition { + /// + /// The module type this definition is definining. + /// Type UIModuleType { get; } } } diff --git a/RecrownedAthenaeum/UI/Skin/Skin.cs b/RecrownedAthenaeum/UI/Skin/Skin.cs index 90f539e..2b4ec6d 100644 --- a/RecrownedAthenaeum/UI/Skin/Skin.cs +++ b/RecrownedAthenaeum/UI/Skin/Skin.cs @@ -7,13 +7,29 @@ using System.Collections.Generic; namespace RecrownedAthenaeum.UI.Skin { + /// + /// A skin is used to group a theme which can then be applied to the UI via the use of modules. + /// public class Skin { + /// + /// Texture atlas containing the skins textures. + /// public readonly TextureAtlas textureAtlas; + /// + /// Colors stored in this skin. + /// public readonly Dictionary colors; + /// + /// Fonts stored in this skin. + /// public readonly Dictionary fonts; Dictionary> definitions; + /// + /// + /// + /// public Skin(TextureAtlas textureAtlas) { this.textureAtlas = textureAtlas;