Documentation for some Animation Editor classes

Source/MBansheeEditor/Utility/EdAnimationCurve.cs

@@ -5,27 +5,72 @@ using BansheeEngine;
 
 namespace BansheeEditor
 {
+    /** @addtogroup AnimationEditor
+     *  @{
+     */
+
+    /// <summary>
+    /// Type of tangent on a keyframe in an animation curve.
+    /// </summary>
     internal enum TangentType
     {
         In = 1 << 0,
         Out = 1 << 1
     }
 
+    /// <summary>
+    /// Flags that are used for describing how are tangents calculated for a specific keyframe in an animation curve. 
+    /// Modes for "in" and "out" tangents can be combined.
+    /// </summary>
     [Flags]
     internal enum TangentMode
     {
-        Auto        = 0,
-        InAuto      = TangentType.In | 1 << 2,
-        InFree      = TangentType.In | 1 << 3,
-        InLinear    = TangentType.In | 1 << 4,
-        InStep      = TangentType.In | 1 << 5,
-        OutAuto     = TangentType.Out | 1 << 6,
-        OutFree     = TangentType.Out | 1 << 7,
-        OutLinear   = TangentType.Out | 1 << 8,
-        OutStep     = TangentType.Out | 1 << 9,
-        Free        = 1 << 10,
+        /// <summary>
+        /// Both tangents are calculated automatically based on the two surrounding keyframes.
+        /// </summary>
+        Auto = 0,
+        /// <summary>
+        /// Left tangent is calculated automatically based on the two surrounding keyframes.
+        /// </summary>
+        InAuto = TangentType.In | 1 << 2,
+        /// <summary>
+        /// Left tangent is manually adjusted by the user.
+        /// </summary>
+        InFree = TangentType.In | 1 << 3,
+        /// <summary>
+        /// Tangent is calculated automatically based on the previous keyframe.
+        /// </summary>
+        InLinear = TangentType.In | 1 << 4,
+        /// <summary>
+        /// Tangent is infinite, ensuring there is a instantaneus jump between previous and current keyframe value.
+        /// </summary>
+        InStep = TangentType.In | 1 << 5,
+        /// <summary>
+        /// Right tangents are calculated automatically based on the two surrounding keyframes.
+        /// </summary>
+        OutAuto = TangentType.Out | 1 << 6,
+        /// <summary>
+        /// Right tangent is manually adjusted by the user.
+        /// </summary>
+        OutFree = TangentType.Out | 1 << 7,
+        /// <summary>
+        /// Tangent is calculated automatically based on the next keyframe.
+        /// </summary>
+        OutLinear = TangentType.Out | 1 << 8,
+        /// <summary>
+        /// Tangent is infinite, ensuring there is a instantaneus jump between current and next keyframe value.
+        /// </summary>
+        OutStep = TangentType.Out | 1 << 9,
+        /// <summary>
+        /// Both tangents are manually adjusted by the user.
+        /// </summary>
+        Free = 1 << 10,
     }
 
+    /// <summary>
+    /// <see cref="AnimationCurve"/> wrapper for use in editor only. Allows easier manipulation of animation keyframes, and
+    /// also stores keyframe tangent modes which are not required for non-editor curves.
+    /// </summary>
     internal class EdAnimationCurve
     {
         private AnimationCurve native;
@@ -33,16 +78,27 @@ namespace BansheeEditor
         private KeyFrame[] keyFrames;
         private TangentMode[] tangentModes;
 
+        /// <summary>
+        /// Returns tangent modes for each keyframe. Array is guaranteed to be the same size as <see cref="KeyFrames"/>.
+        /// If modifying the array values, make sure to call <see cref="Apply"/> to save the changes on the curve.
+        /// </summary>
         public TangentMode[] TangentModes
         {
             get { return tangentModes; }
         }
 
+        /// <summary>
+        /// All keyframes belonging to the animation curve. If modifying the keyframe values, make sure to call 
+        /// <see cref="Apply"/> to save the changes on the curve.
+        /// </summary>
         public KeyFrame[] KeyFrames
         {
             get { return keyFrames; }
         }
 
+        /// <summary>
+        /// Creates a new animation curve with zero keyframes.
+        /// </summary>
         internal EdAnimationCurve()
         {
             keyFrames = new KeyFrame[0];
@@ -51,7 +107,13 @@ namespace BansheeEditor
             tangentModes = new TangentMode[0];
         }
 
-        // Tangent modes should match number of curve keyframes
+        /// <summary>
+        /// Creates a new editor animation curve using an existing animation curve as a basis.
+        /// </summary>
+        /// <param name="native">Animation curve to retrieve the keyframes from.</param>
+        /// <param name="tangentModes">A set of tangent modes for each keyframe. Should be the same size as the number
+        ///                            of keyframes in the provided animation. Can be null in which case all keyframes will
+        ///                            have tangents set to automatic.</param>
         internal EdAnimationCurve(AnimationCurve native, TangentMode[] tangentModes)
         {
             this.native = native;
@@ -80,11 +142,22 @@ namespace BansheeEditor
             return native.Evaluate(time, loop);
         }
 
+        /// <summary>
+        /// Adds a new keyframe to the animation curve. Keyframe will use the automatic tangent mode.
+        /// </summary>
+        /// <param name="time">Time at which to add the keyframe.</param>
+        /// <param name="value">Value of the keyframe.</param>
         internal void AddKeyframe(float time, float value)
         {
             AddKeyframe(time, value, TangentMode.Auto);
         }
 
+        /// <summary>
+        /// Adds a new keyframe to the animation curve.
+        /// </summary>
+        /// <param name="time">Time at which to add the keyframe.</param>
+        /// <param name="value">Value of the keyframe.</param>
+        /// <param name="tangentMode">Tangent mode of the keyframe.</param>
         internal void AddKeyframe(float time, float value, TangentMode tangentMode)
         {
             KeyFrame[] newKeyFrames = new KeyFrame[keyFrames.Length + 1];
@@ -123,6 +196,10 @@ namespace BansheeEditor
             keyFrames = newKeyFrames;
         }
 
+        /// <summary>
+        /// Removes a keyframe at the specified index.
+        /// </summary>
+        /// <param name="index">Index of the keyframe, referencing the <see cref="KeyFrames"/> array.</param>
         internal void RemoveKeyframe(int index)
         {
             if (index < 0 || index >= KeyFrames.Length)
@@ -145,7 +222,14 @@ namespace BansheeEditor
             keyFrames = newKeyFrames;
         }
 
-        // Updates key-frame value and returns new keyframe index
+        /// <summary>
+        /// Updates key-frame time and value. Since keyframes are ordered by time the index of the keyframe might change,
+        /// so a new index of the keyframe is returned by this method. 
+        /// </summary>
+        /// <param name="index">Index of the keyframe to update, referencing the <see cref="KeyFrames"/> array.</param>
+        /// <param name="time">Time to which to set the keyframe.</param>
+        /// <param name="value">Value of the keyframe.</param>
+        /// <returns>New index of the keyframe, referencing the <see cref="KeyFrames"/> array.</returns>
         internal int UpdateKeyframe(int index, float time, float value)
         {
             if (index < 0 || index >= keyFrames.Length)
@@ -198,6 +282,11 @@ namespace BansheeEditor
             return currentKeyIndex;
         }
 
+        /// <summary>
+        /// Changes the tangent mode of a keyframe at the specified index.
+        /// </summary>
+        /// <param name="index">Index of the keyframe to update, referencing the <see cref="KeyFrames"/> array.</param>
+        /// <param name="mode">New tangent mode of the keyframe.</param>
         internal void SetTangentMode(int index, TangentMode mode)
         {
             if (index < 0 || index >= tangentModes.Length)
@@ -206,6 +295,11 @@ namespace BansheeEditor
             tangentModes[index] = mode;
         }
 
+        /// <summary>
+        /// Converts a keyframe tangent (slope) value into a 2D normal vector.
+        /// </summary>
+        /// <param name="tangent">Keyframe tangent (slope).</param>
+        /// <returns>Normalized 2D vector pointing in the direction of the tangent.</returns>
         internal static Vector2 TangentToNormal(float tangent)
         {
             if(tangent == float.PositiveInfinity)
@@ -215,6 +309,11 @@ namespace BansheeEditor
             return Vector2.Normalize(normal);
         }
 
+        /// <summary>
+        /// Converts a 2D normal vector into a keyframe tangent (slope).
+        /// </summary>
+        /// <param name="normal">Normalized 2D vector pointing in the direction of the tangent.</param>
+        /// <returns>Keyframe tangent (slope).</returns>
         internal static float NormalToTangent(Vector2 normal)
         {
             // We know the X value must be one, use that to deduce pre-normalized length
@@ -224,6 +323,9 @@ namespace BansheeEditor
             return MathEx.Sqrt(length*length - 1) * MathEx.Sign(normal.y);
         }
 
+        /// <summary>
+        /// Applies the changes of the editor curve, to the actual underlying animation curve.
+        /// </summary>
         internal void Apply()
         {
             Array.Sort(keyFrames, (x, y) =>
@@ -235,6 +337,9 @@ namespace BansheeEditor
             native.KeyFrames = keyFrames;
         }
 
+        /// <summary>
+        /// Recalculates tangents for all keyframes using the keyframe values and set tangent modes.
+        /// </summary>
         private void UpdateTangents()
         {
             if (keyFrames.Length == 0)
@@ -379,6 +484,9 @@ namespace BansheeEditor
         }
     }
 
+    /// <summary>
+    /// Structure containing a reference to a keyframe as a curve index, and a keyframe index within that curve.
+    /// </summary>
     internal struct KeyframeRef
     {
         public KeyframeRef(int curveIdx, int keyIdx)
@@ -391,6 +499,9 @@ namespace BansheeEditor
         public int keyIdx;
     }
 
+    /// <summary>
+    /// Structure containing a reference to a keyframe tangent, as a keyframe reference and type of the tangent.
+    /// </summary>
     internal struct TangentRef
     {
         public TangentRef(KeyframeRef keyframeRef, TangentType type)
@@ -402,4 +513,6 @@ namespace BansheeEditor
         public KeyframeRef keyframeRef;
         public TangentType type;
     }
+
+    /** @} */
 }

Source/MBansheeEditor/Windows/Animation/GUIAnimEvents.cs

@@ -9,6 +9,10 @@ namespace BansheeEditor
      *  @{
      */
 
+    /// <summary>
+    /// Renders a list of animation events in a form of a timeline. User can set the range of the times to display,
+    /// as well as its physical dimensions.
+    /// </summary>
     public class GUIAnimEvents
     {
         private const int EVENT_HALF_WIDTH = 2;
@@ -25,6 +29,12 @@ namespace BansheeEditor
         private AnimationEvent[] events = new AnimationEvent[0];
         private bool[] selectedEvents = new bool[0];
 
+        /// <summary>
+        /// Constructs a new events timeline and adds it to the specified layout.
+        /// </summary>
+        /// <param name="layout">Layout to add the events GUI to.</param>
+        /// <param name="width">Width of the GUI element in pixels.</param>
+        /// <param name="height">Height of the GUI element in pixels.</param>
         public GUIAnimEvents(GUILayout layout, int width, int height)
         {
             canvas = new GUICanvas();
@@ -33,18 +43,25 @@ namespace BansheeEditor
             SetSize(width, height);
         }
 
-        public bool FindEvent(Vector2I windowCoords, out int eventIdx)
+        /// <summary>
+        /// Attempts to find an event under the provided coordinates.
+        /// </summary>
+        /// <param name="pixelCoords">Coordinates relative to the layout the GUI element is on.</param>
+        /// <param name="eventIdx">Index of the event that was clicked on. Index references the events array as provided
+        ///                        to <see cref="SetEvents"/>. Only valid if method returns true.</param>
+        /// <returns>True if an event was found under the coordinates, false otherwise.</returns>
+        public bool FindEvent(Vector2I pixelCoords, out int eventIdx)
         {
             Rect2I bounds = canvas.Bounds;
 
-            if (windowCoords.x < (bounds.x + GUIGraphTime.PADDING) || windowCoords.x >= (bounds.x + bounds.width - GUIGraphTime.PADDING) ||
-                windowCoords.y < bounds.y || windowCoords.y >= (bounds.y + bounds.height))
+            if (pixelCoords.x < (bounds.x + GUIGraphTime.PADDING) || pixelCoords.x >= (bounds.x + bounds.width - GUIGraphTime.PADDING) ||
+                pixelCoords.y < bounds.y || pixelCoords.y >= (bounds.y + bounds.height))
             {
                 eventIdx = -1;
                 return false;
             }
 
-            Vector2I relativeCoords = windowCoords - new Vector2I(bounds.x + GUIGraphTime.PADDING, bounds.y);
+            Vector2I relativeCoords = pixelCoords - new Vector2I(bounds.x + GUIGraphTime.PADDING, bounds.y);
             for (int i = 0; i < events.Length; i++)
             {
                 AnimationEvent evnt = events[i];
@@ -62,6 +79,11 @@ namespace BansheeEditor
             return false;
         }
 
+        /// <summary>
+        /// Sets the physical size of the GUI element.
+        /// </summary>
+        /// <param name="width">Width in pixels.</param>
+        /// <param name="height">Height in pixels.</param>
         public void SetSize(int width, int height)
         {
             this.width = width;
@@ -73,21 +95,39 @@ namespace BansheeEditor
             drawableWidth = Math.Max(0, width - GUIGraphTime.PADDING * 2);
         }
 
+        /// <summary>
+        /// Sets the range of values over which to display the events.
+        /// </summary>
+        /// <param name="length">Amount of time to display, in seconds.</param>
         public void SetRange(float length)
         {
             rangeLength = Math.Max(0.0f, length);
         }
 
+        /// <summary>
+        /// Returns the offset at which the displayed event values start at.
+        /// </summary>
+        /// <param name="offset">Value to start displaying the events at, in seconds.</param>
         public void SetOffset(float offset)
         {
             rangeOffset = offset;
         }
 
+        /// <summary>
+        /// Number of frames per second, used for rounding up the displayed range.
+        /// </summary>
+        /// <param name="fps">Number of prames per second.</param>
         public void SetFPS(int fps)
         {
             this.fps = Math.Max(1, fps);
         }
 
+        /// <summary>
+        /// Changes the set of displayed animation events.
+        /// </summary>
+        /// <param name="events">Events to display on the timeline.</param>
+        /// <param name="selected">Array of the same size as the <paramref name="events"/> array, determining which
+        ///                        events should be displayed as selected.</param>
         public void SetEvents(AnimationEvent[] events, bool[] selected)
         {
             int numEvents;
@@ -105,6 +145,11 @@ namespace BansheeEditor
                 Array.Copy(selected, selectedEvents, MathEx.Min(numEvents, selected.Length));
         }
 
+        /// <summary>
+        /// Draws a marker for a single event.
+        /// </summary>
+        /// <param name="t">Time to draw the marker at.</param>
+        /// <param name="selected">If true the marker will be drawn as selected.</param>
         private void DrawEventMarker(float t, bool selected)
         {
             int xPos = (int)(((t - rangeOffset) / GetRange()) * drawableWidth) + GUIGraphTime.PADDING;
@@ -123,6 +168,11 @@ namespace BansheeEditor
             canvas.DrawPolyLine(linePoints, outerColor, 100);
         }
 
+        /// <summary>
+        /// Returns the range of times displayed by the timeline rounded to the multiple of FPS.
+        /// </summary>
+        /// <param name="padding">If true, extra range will be included to cover the right-most padding.</param>
+        /// <returns>Time range rounded to a multiple of FPS.</returns>
         private float GetRange(bool padding = false)
         {
             float spf = 1.0f / fps;

Source/MBansheeEditor/Windows/Animation/GUICurveEditor.cs

@@ -10,14 +10,24 @@ namespace BansheeEditor
      *  @{
      */
 
+    /// <summary>
+    /// Displays a set of animation curves and events. Allows manipulation of both by adding, removing and modifying
+    /// curve keyframes, and animation events.
+    /// </summary>
     internal class GUICurveEditor
     {
+        /// <summary>
+        /// Information about currently selected set of keyframes for a specific curve.
+        /// </summary>
         class SelectedKeyframes
         {
             public int curveIdx;
             public List<int> keyIndices = new List<int>();
         }
 
+        /// <summary>
+        /// Information about a keyframe that is currently being dragged.
+        /// </summary>
         struct DraggedKeyframe
         {
             public DraggedKeyframe(int index, KeyFrame original)
@@ -30,6 +40,9 @@ namespace BansheeEditor
             public KeyFrame original;
         }
 
+        /// <summary>
+        /// Information about all keyframes of a specific curve that are currently being dragged.
+        /// </summary>
         class DraggedKeyframes
         {
             public int curveIdx;
@@ -74,7 +87,7 @@ namespace BansheeEditor
         private Vector2I dragStart;
 
         /// <summary>
-        /// Triggers whenever user selects a new frame.
+        /// Triggers whenever user selects a new frame. Reports the index of the selected frame.
         /// </summary>
         public Action<int> OnFrameSelected;
 
@@ -101,7 +114,7 @@ namespace BansheeEditor
         }
 
         /// <summary>
-        /// Returns the offset of the displayed curve values.
+        /// Determines how much to offset the displayed curve values.
         /// </summary>
         public Vector2 Offset
         {
@@ -135,6 +148,13 @@ namespace BansheeEditor
             get { return height; }
         }
 
+        /// <summary>
+        /// Creates a new curve editor GUI elements.
+        /// </summary>
+        /// <param name="window">Parent window of the GUI element.</param>
+        /// <param name="gui">GUI layout into which to place the GUI element.</param>
+        /// <param name="width">Width in pixels.</param>
+        /// <param name="height">Height in pixels.</param>
         public GUICurveEditor(EditorWindow window, GUILayout gui, int width, int height)
         {
             this.window = window;
@@ -201,6 +221,13 @@ namespace BansheeEditor
             return guiCurveDrawing.CurveToPixelSpace(curveCoords);
         }
 
+        /// <summary>
+        /// Converts coordinates in window space (relative to the parent window origin) into coordinates in curve space.
+        /// </summary>
+        /// <param name="windowPos">Coordinates relative to parent editor window, in pixels.</param>
+        /// <param name="curveCoord">Curve coordinates within the range as specified by <see cref="Range"/>. Only
+        ///                          valid when function returns true.</param>
+        /// <returns>True if the coordinates are within the curve area, false otherwise.</returns>
         public bool WindowToCurveSpace(Vector2I windowPos, out Vector2 curveCoord)
         {
             Rect2I elementBounds = GUIUtility.CalculateBounds(gui, window.GUI);
@@ -212,6 +239,10 @@ namespace BansheeEditor
             return guiCurveDrawing.PixelToCurveSpace(drawingPos, out curveCoord);
         }
 
+        /// <summary>
+        /// Handles input. Should be called by the owning window whenever a pointer is pressed.
+        /// </summary>
+        /// <param name="ev">Object containing pointer press event information.</param>
         internal void OnPointerPressed(PointerEvent ev)
         {
             if (ev.IsUsed)
@@ -310,6 +341,10 @@ namespace BansheeEditor
             }
         }
 
+        /// <summary>
+        /// Handles input. Should be called by the owning window whenever a pointer is moved.
+        /// </summary>
+        /// <param name="ev">Object containing pointer move event information.</param>
         internal void OnPointerMoved(PointerEvent ev)
         {
             if (ev.Button != PointerButton.Left)
@@ -452,6 +487,10 @@ namespace BansheeEditor
             }
         }
 
+        /// <summary>
+        /// Handles input. Should be called by the owning window whenever a pointer is released.
+        /// </summary>
+        /// <param name="ev">Object containing pointer release event information.</param>
         internal void OnPointerReleased(PointerEvent ev)
         {
             isPointerHeld = false;
@@ -460,6 +499,10 @@ namespace BansheeEditor
             isMousePressedOverTangent = false;
         }
 
+        /// <summary>
+        /// Handles input. Should be called by the owning window whenever a button is released.
+        /// </summary>
+        /// <param name="ev">Object containing button release event information.</param>
         internal void OnButtonUp(ButtonEvent ev)
         {
             if(ev.Button == ButtonCode.Delete)
@@ -533,6 +576,9 @@ namespace BansheeEditor
             Redraw();
         }
 
+        /// <summary>
+        /// Adds a new keyframe at the currently selected frame.
+        /// </summary>
         public void AddKeyFrameAtMarker()
         {
             ClearSelection();
@@ -551,6 +597,9 @@ namespace BansheeEditor
             guiCurveDrawing.Rebuild();
         }
 
+        /// <summary>
+        /// Rebuilds the entire curve editor GUI.
+        /// </summary>
         public void Redraw()
         {
             guiCurveDrawing.Rebuild();
@@ -559,6 +608,11 @@ namespace BansheeEditor
             guiSidebar.Rebuild();
         }
         
+        /// <summary>
+        /// Changes the tangent mode for all currently selected keyframes.
+        /// </summary>
+        /// <param name="mode">Tangent mode to set. If only in or out tangent mode is provided, the mode for the opposite 
+        ///                    tangent will be kept as is.</param>
         private void ChangeSelectionTangentMode(TangentMode mode)
         {
             foreach (var selectedEntry in selectedKeyframes)
@@ -604,6 +658,9 @@ namespace BansheeEditor
             guiCurveDrawing.Rebuild();
         }
 
+        /// <summary>
+        /// Adds a new keyframe at the position the context menu was opened at.
+        /// </summary>
         private void AddKeyframeAtPosition()
         {
             Vector2 curveCoord;
@@ -626,6 +683,9 @@ namespace BansheeEditor
             }
         }
 
+        /// <summary>
+        /// Removes all currently selected keyframes from the curves.
+        /// </summary>
         private void DeleteSelectedKeyframes()
         {
             foreach (var selectedEntry in selectedKeyframes)
@@ -651,12 +711,19 @@ namespace BansheeEditor
             guiCurveDrawing.Rebuild();
         }
 
+        /// <summary>
+        /// Unselects any selected keyframes.
+        /// </summary>
         private void ClearSelection()
         {
             guiCurveDrawing.ClearSelectedKeyframes();
             selectedKeyframes.Clear();
         }
 
+        /// <summary>
+        /// Adds the provided keyframe to the selection list (doesn't clear existing ones).
+        /// </summary>
+        /// <param name="keyframeRef">Keyframe to select.</param>
         private void SelectKeyframe(KeyframeRef keyframeRef)
         {
             guiCurveDrawing.SelectKeyframe(keyframeRef, true);
@@ -682,6 +749,11 @@ namespace BansheeEditor
             }
         }
 
+        /// <summary>
+        /// Checks is the provided keyframe currently selected.
+        /// </summary>
+        /// <param name="keyframeRef">Keyframe to check.</param>
+        /// <returns>True if selected, false otherwise.</returns>
         private bool IsSelected(KeyframeRef keyframeRef)
         {
             int curveIdx = selectedKeyframes.FindIndex(x =>

Source/MBansheeEditor/Windows/Animation/GUIGraphTime.cs

@@ -51,19 +51,19 @@ namespace BansheeEditor
         /// <summary>
         /// Uses the assigned FPS, range and physical size to calculate the frame that is under the provided coordinates.
         /// </summary>
-        /// <param name="windowCoords">Coordinate relative to the window the GUI element is on.</param>
+        /// <param name="pixelCoords">Coordinate relative to the layout the GUI element is on.</param>
         /// <returns>Frame that was clicked on, or -1 if the coordinates are outside of valid bounds. </returns>
-        public int GetFrame(Vector2I windowCoords)
+        public int GetFrame(Vector2I pixelCoords)
         {
             Rect2I bounds = canvas.Bounds;
 
-            if (windowCoords.x < (bounds.x + PADDING) || windowCoords.x >= (bounds.x + bounds.width - PADDING) ||
-                windowCoords.y < bounds.y || windowCoords.y >= (bounds.y + bounds.height))
+            if (pixelCoords.x < (bounds.x + PADDING) || pixelCoords.x >= (bounds.x + bounds.width - PADDING) ||
+                pixelCoords.y < bounds.y || pixelCoords.y >= (bounds.y + bounds.height))
             {
                 return -1;
             }
 
-            Vector2I relativeCoords = windowCoords - new Vector2I(bounds.x + PADDING, bounds.y);
+            Vector2I relativeCoords = pixelCoords - new Vector2I(bounds.x + PADDING, bounds.y);
 
             float lengthPerPixel = GetRange() / drawableWidth;
             float time = rangeOffset + relativeCoords.x * lengthPerPixel;
@@ -113,7 +113,7 @@ namespace BansheeEditor
         /// <summary>
         /// Returns the offset at which the displayed timeline values start at.
         /// </summary>
-        /// <param name="offset">Value to start the timeline values at.</param>
+        /// <param name="offset">Value to start the timeline values at, in seconds.</param>
         public void SetOffset(float offset)
         {
             rangeOffset = offset;