initial commit

docs/rendering/animation/KeysAnimation.js

@@ -0,0 +1,232 @@
+/**
+ * An abstract Layer for the eye.
+ * @class Layer
+ * @memberof jibo.rendering.animation
+ * @private
+ */
+
+/**
+ * A layer that represents the Eye.
+ * @class EyeLayer
+ * @memberof jibo.rendering.animation
+ * @private
+ */
+
+/**
+ * A layer of the KeysAnimation class that represents a timeline animation.
+ * @class TimelineLayer
+ * @memberof jibo.rendering.animation
+ * @private
+ * @param {Number} index The depth index.
+ * @param {String} name Name of the timeline.
+ * @param {jibo.rendering.animation.Timeline} timeline
+ * @param {Number} startTime The starting time of this animation in seconds.
+ * @param {Boolean} attach `true` if Timeline should be attached to the eye's position.
+ * @param {String} offset The frame offset to start playing the animation at
+ */
+
+    /**
+     * Update the position of the animation.
+     * @method jibo.rendering.animation.TimelineLayer#update
+     * @param {Number} time Global time of the animation in seconds.
+     */
+
+    /**
+     * Destroy and don't use after this.
+     * @method jibo.rendering.animation.TimelineLayer#destroy
+     */
+
+/**
+ * Class used by Animation Utilities to provide playback
+ * of keys files.
+ * @class KeysAnimation
+ * @memberof jibo.rendering.animation
+ * @extends EventEmitter
+ * @param {String} id The name of the keys file.
+ */
+
+    /**
+     * The default framerate.
+     * @name jibo.rendering.animation.KeysAnimation.FRAMERATE
+     * @type {String}
+     * @default 30
+     */
+
+    /**
+     * Event name when animation starts.
+     * @name jibo.rendering.animation.KeysAnimation.STARTED
+     * @type {String}
+     */
+
+    /**
+     * Event name when animation stops.
+     * @name jibo.rendering.animation.KeysAnimation.STOPPED
+     * @type {String}
+     */
+
+    /**
+     * Event name when builder event is fired.
+     * @name jibo.rendering.animation.KeysAnimation.EVENT
+     * @type {String}
+     */
+
+    /**
+     * Event name when animation is cancelled.
+     * @name jibo.rendering.animation.KeysAnimation.CANCELLED
+     * @type {String}
+     */
+
+    /**
+     * Event name when audio is played.
+     * @name jibo.rendering.animation.KeysAnimation.PLAY_AUDIO
+     * @type {String}
+     */
+
+    /**
+     * Event name when timeline is played.
+     * @name jibo.rendering.animation.KeysAnimation.PLAY_TIMELINE
+     * @type {String}
+     */
+
+    /**
+     * Event name when timeline needs to be reordered.
+     * @name jibo.rendering.animation.KeysAnimation.REORDER
+     * @type {String}
+     */
+
+    /**
+     * Event when the timeline is updated.
+     * @name jibo.rendering.animation.KeysAnimation.UPDATE
+     * @type {String}
+     * @param {Number} time The current time in seconds from the start of animation.
+     * @param {Object} dofValues Collection of DOF values for the current frame.
+     */
+
+    /**
+     * Asset Pack name.
+     * @name jibo.rendering.animation.KeysAnimation#assetPack
+     * @type {String}
+     */
+
+    /**
+     * Resource root for animation (defaults to root of skill).
+     * @name jibo.rendering.animation.KeysAnimation#root
+     * @type {String}
+     */
+
+    /**
+     * Id of the keys file in the cache.
+     * @name jibo.rendering.animation.KeysAnimation#id
+     * @type {String}
+     */
+
+    /**
+     * Name of the keys file.
+     * @name jibo.rendering.animation.KeysAnimation#name
+     * @type {String}
+     */
+
+    /**
+     * The collection of layers for the animation.
+     * @name jibo.rendering.animation.KeysAnimation#layers
+     * @type {Array<Layer>}
+     */
+
+    /**
+     * Token of an asset load for our keys data, so it doesn't get unloaded under us.
+     * @private
+     */
+
+    /**
+     * Map of Timeline objects.
+     * @name jibo.rendering.animation.KeysAnimation#timelines
+     * @type {Object}
+     */
+
+    /**
+     * Map of PIXI.Texture objects.
+     * @name jibo.rendering.animation.KeysAnimation#textures
+     * @type {Object}
+     */
+
+    /**
+     * Map of Sound objects.
+     * @name jibo.rendering.animation.KeysAnimation#sounds
+     * @type {Object}
+     */
+
+    /**
+     * The animation options.
+     * @name jibo.rendering.animation.KeysAnimation#options
+     * @type {AnimationOptions<DOFSet>}
+     * @private
+     */
+
+    /**
+     * The animation instance.
+     * @name jibo.rendering.animation.KeysAnimation#instance
+     * @type {AnimationInstance}
+     * @private
+     */
+
+    /**
+     * Update the timelines.
+     * @method jibo.rendering.animation.KeysAnimation#update
+     * @param {Number} time Current time of this animation
+     */
+
+    /**
+     * Set the keys animation data.
+     * @name jibo.rendering.animation.KeysAnimation#data
+     * @type {Object}
+     * @private
+     */
+
+    /**
+     * Sync a movieclip to the playback of the animation.
+     * @method jibo.rendering.animation.KeysAnimation#playSync
+     * @param {animate.MovieClip} instance The clip to play.
+     * @param {String|Function} [event] The name of the event label or callback function.
+     * @param {Function} [callback] Callback when play is complete.
+     */
+
+    /**
+     * Destroy the keys animation completely, after the Expression Service has told us that it has finished playing.
+     * @method jibo.rendering.animation.KeysAnimation#destroyWhenComplete
+     */
+
+    /**
+     * Destroy the keys animation completely.
+     * @method jibo.rendering.animation.KeysAnimation#destroy
+     */
+
+    /**
+     * Handle animation custom events.
+     * @method jibo.rendering.animation.KeysAnimation#onEvent
+     * @private
+     */
+
+    /**
+     * Handle playing audio within the animation.
+     * @method jibo.rendering.animation.KeysAnimation#onPlayAudio
+     * @private
+     * @param {Object} payload
+     * @param {string} payload.file
+     */
+
+    /**
+     * Reorder the layers of the animation.
+     * @method jibo.rendering.animation.KeysAnimation#reorder
+     * @private
+     */
+
+    /**
+     * Handle the playing of a timeline event.
+     * @method jibo.rendering.animation.KeysAnimation#onPlayTimeline
+     * @private
+     * @param {object} payload
+     * @param {string} payload.file
+     * @param {number} payload.layerNum
+     * @param {boolean} payload.attach
+     * @param {string} payload.offset
+     */

docs/rendering/animation/KeysData.js

@@ -0,0 +1,126 @@
+/**
+ * Class used by Animation Utilities to provide playback
+ * of keys files.
+ * @class KeysData
+ * @memberof jibo.rendering.animation
+ * @extends EventEmitter
+ * @param {String} id The name of the keys file.
+ * @param {String} src The absolute path of the keys file.
+ * @param {String} cache The name of the cache the data was originally loaded into.
+ */
+
+    /**
+     * Asset Pack name.
+     * @name jibo.rendering.animation.KeysData#assetPack
+     * @type {String}
+     */
+
+    /**
+     * Resource root for animation (defaults to root of skill).
+     * @name jibo.rendering.animation.KeysData#root
+     * @type {String}
+     */
+
+    /**
+     * Source path of animation data
+     * @name jibo.rendering.animation.KeysData#src
+     * @type {String}
+     */
+
+    /**
+     * Source path of corresponding `.anim`, if present/valid.
+     * @name jibo.rendering.animation.KeysData#dotAnimSrc
+     * @type {String}
+     */
+
+    /**
+     * Name of the initial cache this data was loaded into. Used when determining animation options.
+     * @name jibo.rendering.animation.KeysData#cache
+     * @type {String}
+     */
+
+    /**
+     * Map of Timeline objects.
+     * @name jibo.rendering.animation.KeysData#timelines
+     * @type {Object}
+     */
+
+    /**
+     * Map of PIXI.Texture objects.
+     * @name jibo.rendering.animation.KeysData#textures
+     * @type {Object}
+     */
+
+    /**
+     * Map of Sound objects.
+     * @name jibo.rendering.animation.KeysData#sounds
+     * @type {Object}
+     */
+
+    /**
+     * Name of the keys file.
+     * @name jibo.rendering.animation.KeysData#id
+     * @type {String}
+     */
+
+    /**
+     * The keys animation data.
+     * @name jibo.rendering.animation.KeysData#data
+     * @type {Object}
+     * @private
+     */
+
+    /**
+     * Add a sound to the animation for playing.
+     * @method jibo.rendering.animation.KeysData#addSound
+     * @param {String} id The ID of the sound
+     * @param {jibo.sound.Sound} sound Instance of sound.
+     */
+
+    /**
+     * Add a timeline to the animation for playing.
+     * @method jibo.rendering.animation.KeysData#addTimeline
+     * @param {String} id The ID of the timeline
+     * @param {jibo.rendering.animation.Timeline} timeline Instance of timeline.
+     */
+
+    /**
+     * Add a PIXI texture to the animation for playback.
+     * @method jibo.rendering.animation.KeysData#addTexture
+     * @param {String} id The ID of the texture
+     * @param {PIXI.Texture} texture Instance of texture.
+     */
+
+    /**
+     * Create a shallow clean copy of this KeysAnimation object resetting all state.
+     * This should be used when retrieving a keys animation object from cache
+     * Note: Any clean copy should always be destroyed after use
+     * @param {CloneOptions<DOFSet>} options Options for animation instantiation/playback.
+     * @method jibo.rendering.animation.KeysData#getCleanCopy
+     * @return {Promise<jibo.rendering.animation.KeysData>}
+     */
+
+    /**
+     * Create and immediately play a KeysAnimation from this KeysData.
+     * Event handlers for `stopped`, `cancelled`, `rejected`, and other animation events must be registered to the
+     * animation instance immediately (in-stack) upon promise resolution, or else they may be missed.
+     * @param {CloneOptions<DOFSet>} [options] Options for animation instantiation/playback.
+     * @param {string} [requestor] The system making the animation playback request.
+     * @method jibo.rendering.animation.KeysData#getAndPlayAnim
+     * @return {Promise<jibo.rendering.animation.KeysAnimation>}
+     */
+
+    /**
+     * Destroy the keys data completely.
+     * @method jibo.rendering.animation.KeysData#destroy
+     */
+
+    /**
+     * Create an animation options from keyframes data or a keyframes file.
+     * In the case of keyframes data, DOF values are computed and passed to the expression service.
+     * In the case of a keyframes file, the path to a file of DOF values computed from the keyframes file is passed
+     * to the expression service.
+     * @method jibo.rendering.animation.KeysData#createAnimOptions
+     * @return {AnimationOptions<DOFSet>}
+     * @private
+     */

docs/rendering/animation/KeysLoader.js

@@ -0,0 +1,129 @@
+    /**
+     * Nested Keys File Loading.
+     *
+     * Given a keys file url, load the file and then recursively
+     * composite into it any keys files it points to (somewhat like macro expansion).
+     * @return {String} The result of the compositing operation with all reference layers removed.
+     * @name jibo.rendering.animation.KeysLoader#innerNestedLoad
+     * @param {String} url Path nanme of the keys file to be loaded
+     * @param {Callback} complete Callback to call when the load is completed.
+     * @param {String} [parentId] The layer ID of the referencing frame.
+     * @param {String} [refBase] The directory that the asset references are with respect to.
+     * @private
+     */
+
+    /**
+     * Convert keyframes referencing texture, pixi and audio information into assetpack style references if necessary.
+     *
+     * The motivation:
+     * Consider a reference layer in a skill's animation that references an animDB keys file.
+     * Compositing will pull in the layers from the animDB keys file, but any asset references (textures, audio, pixi)
+     * in those layers will be relative to the animDB root. If the paths to those assets are not converted to
+     * asset-pack style references (while we know their provenance) we will not be able to distinguish later on
+     * whether those references are relative to the animDB or to the local skill.
+     *
+     * @param {Keyframes} frames the keyframes object whose asset references will be modified.
+     * @param {string} assetPack the assetPack that the containing file is in.
+     */
+
+    /**
+     * Convert a non-asset pack reference into an asset-pack one.
+     * @param assetPack
+     * @param filepath
+     * @returns {string}
+     */
+
+    /**
+     * Find all references in a keys file, returning them in reverse-order.
+     * @name jibo.rendering.animation.KeysLoader#getKeyFileReferences
+     * @param {Keyframes} frames A keyframes structure containing reference layers.
+     * @param {String} refBase The directory containing the file from whence the given keyframes were loaded.
+     * @returns {Array} An array of objects describing references to other keys files,
+     * each object has these properties:
+     * `url`: the url of the file being referenced,
+     * `parentId`: the layerID of the parent,
+     * `holdFinalPose`: whether the final frame of the referenced layer is held until the next reference (or end),
+     * `containerDuration`: the duration of the file that contains this reference.
+     * `layerNumber`: the ordinal layer number of the reference,
+     * `atEnd`: a boolean that is true if this is the last reference in the layer.
+     * `nextRefStart`: where the next reference frame is, or Infinity if there are no further references.
+     * `timeOffset`: the timepoint at which it is to be inserted in the referencing layer.
+     * @private
+     */
+
+    /**
+     * Place num in a leading-zero-padded field of the given size
+     * @param {number} num Number to pad
+     * @param {number} size Size of final field
+     * @returns {string}
+     */
+
+    /**
+     * Return a full URL for the referenced keys file based on
+     * the reference mode (by name or by file).
+     * @param {any} keyframe the keyframe containing the reference.
+     * @param {string} refBase directory of the file in which the reference is occurring.
+     * @returns {object} object.url containing the fully resolved path to referenced file and
+     * object.refBase containing the parent directory of the referencer.
+     * @method jibo.rendering.animation.KeysLoader#getReferencedUrl
+     * @private
+     */
+
+    /**
+     * Find any "HOLD_SAFE" events in referenced layers and remove them (by renaming them).
+     * @name jibo.rendering.animation.KeysLoader#removeHoldSafesInReferences
+     * @param {Keyframes} frames keyframes to be cleaned.
+     * @private
+     */
+
+    /**
+     * Strip out any reference-type layers from the keyframes.
+     * @name jibo.rendering.animation.KeysLoader#removeReferenceLayers
+     * @param {Keyframes} keyframes keyframes structure containing reference layers.
+     * @private
+     */
+
+    /**
+     * Shift the layer's validFrom, validUpto and validHoldAfter properties and
+     * shift the timepoint of all the keyframes within each of the given layers by the given time offset ("validFrom").
+     * The validFrom and validUpto parameters are in "referencing" layer coordinates.
+     * @name jibo.rendering.animation.KeysLoader#timeshift
+     * @param {Keyframes} frames the layers containing the keyframes to be shifted.
+     * @param {number} validFrom the beginning of the valid region.
+     * @param {number} validUpto the ending of valid region, or Infinity for unlimited.
+     * @param {number} holdAfter the timepoint after which the pose does not change (i.e. it remains fixed at that timepoint).
+     * @private
+     */
+
+    /**
+     * Insert all the layers of toBeInsertedKeyframes into existingKeyframes at the given layer number.
+     * Insert them last-first in order to preserve their original ordering at the designated layer.
+     * @name jibo.rendering.animation.KeysLoader#composite
+     * @param {Number} layerNumber the layer number in which the keyframes are to be inserted.
+     * @param {Keyframes} existingKeyframes the existing keyframes into which the layers will be inserted.
+     * @param {Keyframes} toBeInsertedKeyframes the source of the keyframes to be inserted.
+     * @private
+     */
+
+    /**
+     * Modifies the layer ids to prefixed by the referencing layer's id (delimited by "-")
+     * and suffixed with the layer number (delimited by '.').
+     * @name jibo.rendering.animation.KeysLoader#fixLayerIds
+     * @param {Keyframes} frames the set of layers to be modified.
+     * @param {string} prefix the string with which to prefix each layer id.
+     * @private
+     */
+
+    /**
+     * Was this layer produced from a keyframes reference?
+     * @name jibo.rendering.animation.KeysLoader#isReferencedLayer
+     * @param {any} layer the layer to be checked
+     * @returns {boolean}
+     * @private
+     */
+
+ /**
+    //  * Return true if frame being referenced already exists in hierarchy.
+    //  * @param frames
+    //  * @param prefix
+    //  */

docs/rendering/animation/Shapes.js

@@ -0,0 +1,12 @@
+/**
+ * The object returned by the ShapesTask.
+ * @class Shapes
+ * @memberof jibo.rendering.animation
+ * @param {String} id ID for the shapes.
+ * @param {Array<Array>} shapes Collection of shapes.
+ */
+
+    /**
+     * Destroys shapes object.
+     * @method jibo.rendering.animation.Shapes#destroy
+     */

docs/rendering/animation/Spritesheet.js

@@ -0,0 +1,19 @@
+/**
+ * The object returned by the SpritesheetTask.
+ * @class Spritesheet
+ * @memberof jibo.rendering.animation
+ * @param {PIXI.BaseTexture} baseTexture
+ * @param {Object} frames The frames map
+ * @param {Number} resolution The amount of scale
+ */
+
+    /**
+     * The collection of textures by name.
+     * @name jibo.rendering.animation.Spritesheet#frames
+     * @type {Object}
+     */
+
+    /**
+     * Destroys all the textures/frames of spritesheet.
+     * @method jibo.rendering.animation.Spritesheet#destroy
+     */

docs/rendering/animation/Timeline.js

@@ -0,0 +1,48 @@
+/**
+ * The object returned by the TimelineTask. Represents a PIXI animation.
+ * @class Timeline
+ * @private
+ * @memberof jibo.rendering.animation
+ */
+
+    /**
+     * Adds a texture for the Timeline.
+     * @method jibo.rendering.animation.Timeline#addTexture
+     * @private
+     * @param {PIXI.Texture} texture Texture reference.
+     * @param {String} id The id name of texture in cache.
+     */
+
+    /**
+     * Gets a texture/frame that was loaded for this Timeline
+     * @method jibo.rendering.animation.Timeline#getTexture
+     * @private
+     * @param {String} id The id name of texture in cache.
+     * @returns {PIXI.Texture} Texture reference.
+     */
+
+    /**
+     * Adds shapes to the Timeline.
+     * @method jibo.rendering.animation.Timeline#addShapes
+     * @private
+     * @param {jibo.rendering.animation.Shapes} shapes Texture reference.
+     */
+
+    /**
+     * Adds spritesheet to the Timeline.
+     * @method jibo.rendering.animation.Timeline#addSpritesheet
+     * @private
+     * @param {jibo.rendering.animation.Spritesheet} spritesheet Spritesheet reference.
+     */
+
+    /**
+     * Uploads all the textures to the GPU.
+     * @method jibo.rendering.animation.Timeline#upload
+     * @param {PIXI.WebGLRenderer} renderer Reference to face renderer.
+     * @param {Function} callback Callback when complete.
+     */
+
+    /**
+     * Destroys Timeline object.
+     * @method jibo.rendering.animation.Timeline#destroy
+     */