More documentation.

Author: jcc10

client-ts/animation-helpers.ts

@@ -1,16 +1,48 @@
 import { dof8, dof8Set } from "./dof8.ts";
 
+/**
+ * A float that should be between 0 and 1.
+ * Where 0 is the start of the animation and 1 is the end.
+ */
+export declare type timeFloat = number;
+
+/**
+ * Converts degrees to radians (what THREE.js uses)
+ * @param degrees degrees input
+ */
 export function degreesToRadians(degrees: number): number {
     const pi = Math.PI;
     return degrees * (pi / 180);
 }
 
+/**
+ * Converts degrees to radians (what THREE.js uses)
+ * Alias for degreesToRadians function.
+ * @param degrees  degrees input
+ */
+export function d2r(degrees: number): number {
+    return degreesToRadians(degrees);
+}
+
+/**
+ * Preforms a fade from transparent to opaque.
+ * Shorthand for fading in a object at start of animation.
+ * @param t animation timestamp in ms
+ * @param duration duration in ms
+ */
 export function fadeIn(t: number, duration: number): dof8 {
     const tSub = timeSubset(t, 0, duration);
     const alpha = linearChange(tSub, 0, 1);
     return { alpha };
 }
 
+/**
+ * Preforms a fade from opaque to transparent.
+ * Shorthand for fading out a object at the end of animation.
+ * @param t animation timestamp in ms
+ * @param duration duration in ms
+ * @param endPoint the time the animation should end at
+ */
 export function fadeOut(t: number, duration: number, endPoint: number): dof8 {
     const tSub = timeSubset(t, (endPoint - duration), endPoint);
     const alpha = linearChange(tSub, 1, 0);
@@ -23,7 +55,7 @@ export function fadeOut(t: number, duration: number, endPoint: number): dof8 {
  * @param startT timecode for 0
  * @param endT timecode for 1
  */
-export function timeSubset(t: number, startT: number, endT: number){
+export function timeSubset(t: number, startT: number, endT: number): timeFloat{
     const range = endT - startT;
     return (t - startT) / range;
 }
@@ -32,15 +64,22 @@ export function timeSubset(t: number, startT: number, endT: number){
  * Linear change function.
  * 
  * Partially because I'm bad at math and forget the equation snippet.
- * @param t float from 0 to 1 (0 being start, 1 being end)
+ * @param t timeFloat
  * @param start Starting Value
  * @param end Ending Value
  */
-export function linearChange(t: number, start: number, end: number): number {
+export function linearChange(t: timeFloat, start: number, end: number): number {
     return (t * (end - start)) + start;
 }
 
-export function spin(t: number, start: dof8, end: dof8): dof8 {
+/**
+ * Spins a object from the starting configuration to the ending configuration.
+ * Both starting and ending dof8 values must be set for the output to include them.
+ * @param t timeFloat
+ * @param start starting set of dof8 values
+ * @param end ending set of dof8 values
+ */
+export function spin(t: timeFloat, start: dof8, end: dof8): dof8 {
     const out: dof8 = {};
     if (start.X != undefined && end.X != undefined) {
         out.X = linearChange(t, start.X, end.X);
@@ -104,6 +143,12 @@ function mergeAlpha(a: number | undefined, b: number | undefined): number | unde
     }
 }
 
+/**
+ * Merges (adds) values of two dof8 records.
+ * If only one object has data, it will be copied.
+ * @param a first dof8 object
+ * @param b second dof8 object
+ */
 export function mergeDof8(a: dof8, b: dof8): dof8 {
     const output: dof8 = {};
     output.x = mergeLower(a.x, b.x);
@@ -117,6 +162,12 @@ export function mergeDof8(a: dof8, b: dof8): dof8 {
     return output;
 }
 
+/**
+ * Merges two dof8Sets using the mergeDof8 function.
+ * If only one object has data, it will be copied.
+ * @param input dof8Set to merge
+ * @param offset dof8Set to merge
+ */
 export function offsetMerge(input: dof8Set, offset: dof8Set): dof8Set {
     const output: dof8Set = {};
     for (const r in input) {

client-ts/dof8.ts

@@ -1,3 +1,10 @@
+/**
+ * 8 Degrees of Freedom interface.
+ * lowercase: positional.
+ * uppercase: rotational (in radians).
+ * scale: scale.
+ * alpha: opacity. (0: transparent, 1: opaque)
+ */
 export interface dof8 {
     x?: number,
     y?: number,
@@ -9,4 +16,8 @@ export interface dof8 {
     alpha?: number,
 }
 
+/**
+ * Object Name -> dof8 set
+ * Used for sending state updates.
+ */
 export type dof8Set = Record<string, dof8>;