Merge pull request #10911 from jostschmithals/animationDocs

Additions to animation docs

docs/api/animation/AnimationAction.html

@@ -11,121 +11,352 @@
     <h1>[name]</h1>
 
     <div class="desc">
-    An AnimationAction schedules clip playback on specific objects.
+        AnimationActions schedule the performance of the animations which are stored in
+        [page:AnimationClip AnimationClips].<br /><br />
+        
+        Note: Most of AnimationAction's methods can be chained.<br /><br />
+        
+        For an overview of the different elements of the three.js animation system see the
+        "Animation System" article in the "Next Steps" section of the manual.
     </div>
-
+    
 
     <h2>Constructor</h2>
-
+    
 
     <h3>[name]( [page:AnimationMixer mixer], [page:AnimationClip clip], [page:Object3D localRoot] )</h3>
-
-
+    <div>       
+        [page:AnimationMixer mixer] - the *AnimationMixer* that is controlled by this action.<br />
+        [page:AnimationClip clip] - the *AnimationClip* that holds the animation data for this action.<br />
+        [page:Object3D localRoot] - the root object on which this action is performed.<br /><br />
+        
+        Note: Instead of calling this constructor directly you should instantiate an AnimationAction with 
+        [page:AnimationMixer.clipAction] since this method provides caching for better performance.
+    </div>   
+    
+   
     <h2>Properties</h2>
+       
+        
+    <h3>[property:Boolean clampWhenFinished]</h3>
+    <div>
+        If *clampWhenFinished* is set to true the animation will automatically be [page:.paused paused] 
+        on its last frame.<br /><br />
+         
+        If *clampWhenFinished* is set to false, [page:.enabled enabled] will automatically be switched 
+        to false when the last loop of the action has finished, so that this action has no further 
+        impact.<br /><br />
+        
+        Default is false.<br /><br />
+        
+        Note: *clampWhenFinished* has no impact if the action is interrupted (it has only an effect if 
+        its last loop has really finished).
+    </div>    
+
+    <h3>[property:Boolean enabled]</h3>
+    <div>
+        Setting *enabled* to *false* disables this action, so that it has no impact. Default is *true*.<br /><br />
+        
+        When the action is re-enabled, the animation continues from its current [page:.time time] 
+        (setting *enabled* to *false* doesn't reset the action).<br /><br />
+
+        Note: Setting *enabled* to *true* doesn’t automatically restart the animation. Setting *enabled* 
+        to *true* will only restart the animation immediately if the following condition is fulfilled: 
+        [page:.paused paused] is *false*, this action has not been deactivated in the meantime (by 
+        executing a [page:.stop stop] or [page:.reset reset] command), and neither [page:.weight weight] 
+        nor [page:.timeScale timeScale] is 0.
+    </div>
+    
+    <h3>[property:Number loop]</h3>
+    <div>
+        The looping mode (can be changed with [page:.setLoop setLoop]). Default is 
+        [page:Animation THREE.LoopRepeat] (with an infinite number of [page:.repetitions repetitions])<br /><br />
+        
+        Must be one of these constants:<br /><br /> 
+        [page:Animation THREE.LoopOnce] - playing the clip once,<br /> 
+        [page:Animation THREE.LoopRepeat] - playing the clip with the choosen number of *repetitions*, 
+        each time jumping from the end of the clip directly to its beginning,<br /> 
+        [page:Animation THREE.LoopPingPong] - playing the clip with the choosen number of *repetitions*, 
+        alternately playing forward and backward.
+    </div>
+    
+    <h3>[property:Boolean paused]</h3>
+    <div>
+        Setting *paused* to *true* pauses the execution of the action by setting the effective time scale
+        to 0. Default is *false*.<br /><br />
+    </div>    
+    
+    <h3>[property:Number repetitions]</h3>
+    <div>
+        The number of repetitions of the performed [page:AnimationClip] over the course of this action.
+        Can be set via [page:.setLoop setLoop]. Default is *Infinity*.<br /><br />
+        Setting this number has no effect, if the [page:.loop loop mode] is set to 
+        [page:Animation THREE.LoopOnce].<br /><br />
 
+        Note: The first run is not taken into account. For example: if *repetition* is set to 2, the 
+        total number of executed rounds will be 3.
+    </div>
 
     <h3>[property:Number time]</h3>
+    <div>
+        The local time of this action (in seconds, starting with 0).<br /><br />
+        
+        The value gets clamped or wrapped to 0...clip.duration (according to the loop state). It can be 
+        scaled relativly to the global mixer time by changing [page:.timeScale timeScale] (using 
+        [page:.setEffectiveTimeScale setEffectiveTimeScale] or [page:.setDuration setDuration]).<br />
+    </div>
 
     <h3>[property:Number timeScale]</h3>
+    <div>  
+        Scaling factor for the [page:.time time]. A value of 0 causes the animation to pause. Negative 
+        values cause the animation to play backwards. Default is 1.<br /><br />
+        Properties/methods concerning *timeScale* (respectively *time*) are:
+        [page:.getEffectiveTimeScale getEffectiveTimeScale], 
+        [page:.halt halt], 
+        [page:.paused paused], 
+        [page:.setDuration setDuration], 
+        [page:.setEffectiveTimeScale setEffectiveTimeScale], 
+        [page:.stopWarping stopWarping],
+        [page:.syncWith syncWith], 
+        [page:.warp warp]. 
+    </div>    
 
     <h3>[property:Number weight]</h3>
+    <div>
+        The degree of influence of this action (in the interval [0, 1]). Values between 0 (no impact) 
+        and 1 (full impact) can be used to blend between several actions. Default is 1. <br /><br />
+        Properties/methods concerning  *weight* are:
+        [page:.crossFadeFrom crossFadeFrom], 
+        [page:.crossFadeTo crossFadeTo], 
+        [page:.enabled enabled], 
+        [page:.fadeIn fadeIn], 
+        [page:.fadeOut fadeOut], 
+        [page:.getEffectiveWeight getEffectiveWeight], 
+        [page:.setEffectiveWeight setEffectiveWeight], 
+        [page:.stopFading stopFading].
+    </div>
 
-    <h3>[property:Number loop]</h3>
-
-    <h3>[property:Number repetitions]</h3>
-
-    <h3>[property:Boolean paused]</h3>
-
-    <h3>[property:Boolean enabled]</h3>
-
-    <h3>[property:Boolean clampWhenFinished]</h3>
-
+    <h3>[property:Boolean zeroSlopeAtEnd]</h3>
+    <div>
+        Enables smooth interpolation without separate clips for start, loop and end. Default is *true*.
+    </div>
+    
     <h3>[property:Boolean zeroSlopeAtStart]</h3>
+    <div>
+        Enables smooth interpolation without separate clips for start, loop and end. Default is *true*.
+    </div>
+    
 
-    <h3>[property:Boolean zeroSlopeAtEnd]</h3>
+    <h2>Methods</h2> 
+       
 
+    <h3>[method:AnimationAction crossFadeFrom]( [page:AnimationAction fadeOutAction], [page:Number durationInSeconds], [page:Boolean warpBoolean] )</h3>
+    <div>
+        Causes this action to [page:.fadeIn fade in], fading out another action simultaneously, within 
+        the passed time interval. This method can be chained.<br /><br />
+        
+        If warpBoolean is true, additional [page:.warp warping] (gradually changes of the time scales) 
+        will be applied.<br /><br />
+        
+        Note: Like with *fadeIn*/*fadeOut*, the fading starts/ends with a weight of 1.
+        
+    </div>
 
-    <h2>Methods</h2>
+    <h3>[method:AnimationAction crossFadeTo]( [page:AnimationAction fadeInAction], [page:Number durationInSeconds], [page:Boolean warpBoolean] )</h3>
+    <div>
+        Causes this action to [page:.fadeOut fade out], fading in another action simultaneously, within 
+        the passed time interval. This method can be chained.<br /><br />
+        If warpBoolean is true, additional [page:.warp warping] (gradually changes of the time scales) 
+        will be applied.<br /><br />
+        
+        Note: Like with *fadeIn*/*fadeOut*, the fading starts/ends with a weight of 1.
+    </div>    
+
+    <h3>[method:AnimationAction fadeIn]( [page:Number durationInSeconds] )</h3>
+    <div>
+        Increases the [page:.weight weight] of this action gradually from 0 to 1, within the passed time 
+        interval. This method can be chained.
+    </div>
 
+    <h3>[method:AnimationAction fadeOut]( [page:Number durationInSeconds] )</h3>
+    <div>
+        Decreases the [page:.weight weight] of this action gradually from 1 to 0, within the passed time 
+        interval. This method can be chained.
+    </div>
+    
+    <h3>[method:Number getEffectiveTimeScale]()</h3>
+    <div>
+        Returns the effective time scale (considering the current states of warping and 
+        [page:.paused paused]).
+    </div>
 
-    <h3>[method:AnimationAction play]()</h3>
+    <h3>[method:number getEffectiveWeight]()</h3>
+    <div>
+        Returns the effective weight (considering the current states of fading and 
+        [page:.enabled enabled]).
+    </div>
 
-    <h3>[method:AnimationAction stop]()</h3>
+    <h3>[method:AnimationClip getClip]()</h3>
+    <div>
+        Returns the clip which holds the animation data for this action.
+    </div>
 
-    <h3>[method:AnimationAction reset]()</h3>
+    <h3>[method:AnimationMixer getMixer]()</h3>
+    <div>
+        Returns the mixer which is responsible for playing this action.
+    </div>
+
+    <h3>[method:Object3D getRoot]()</h3>
+    <div>
+        Returns the root object on which this action is performed.
+    </div>    
+    
+    <h3>[method:AnimationAction halt]( [page:Number durationInSeconds] )</h3>
+    <div>
+        Decelerates this animation's speed to 0 by decreasing [page:.timeScale timeScale] gradually 
+        (starting from its current value), within the passed time interval. This method can be chained.
+    </div>    
 
     <h3>[method:Boolean isRunning]()</h3>
+    <div>
+        Returns true if this action is activated in the mixer and currently playing (as opposed to 
+        [page:.isScheduled isScheduled]).<br /><br />
+         
+        In addition to being activated in the mixer the following conditions must be fulfilled: 
+        [page:.paused paused] is equal to false, [page:.enabled enabled] is equal to true, 
+        [page:.timeScale timeScale] is different from 0, and there is no scheduling for a delayed start 
+        ([page:.startAt startAt]).
+    </div>
 
     <h3>[method:Boolean isScheduled]()</h3>
+    <div>
+        Returns true, if this action is activated in the mixer.<br /><br />
+        Note: This doesn’t necessarily mean that the animation is actually running (compare the additional 
+        conditions for [page:.isRunning isRunning]).
+    </div>
 
-    <h3>[method:AnimationAction startAt]()</h3>
-
-    <h3>[method:AnimationAction setLoop]( [page:Number mode], [page:Number repetitions] )</h3>
-
-    <h3>[method:AnimationAction setEffectiveWeight]( [page:Number weight] )</h3>
-
-    <h3>[method:number getEffectiveWeight]()</h3>
-
-    <h3>[method:AnimationAction fadeIn]( [page:Number duration] )</h3>
-
-    <h3>[method:AnimationAction fadeOut]( [page:Number duration] )</h3>
-
-    <h3>[method:AnimationAction crossFadeFrom]( [page:AnimationAction fadeOutAction], [page:Number duration], [page:Boolean warp] )</h3>
+    <h3>[method:AnimationAction play]()</h3>
+    <div>
+        Tells the mixer to activate the action. This method can be chained.<br /><br />
+        
+        Note: Activating this action doesn’t necessarily mean that the animation starts immediately: 
+        If the action had already finished before (by reaching the end of its last loop), or if a time 
+        for a delayed start has been set (via [page:.startAt startAt]), a [page:.reset reset] must be 
+        executed first. Some other settings ([page:.paused paused]=true, [page:.enabled enabled]=false, 
+        [page:.weight weight]=0, [page:.timeScale timeScale]=0) can prevent the animation from playing, 
+        too.
+    </div>
 
-    <h3>[method:AnimationAction crossFadeTo]( [page:AnimationAction fadeInAction], [page:Number duration], [page:Boolean warp] )</h3>
+    <h3>[method:AnimationAction reset]()</h3>
+    <div>
+        Resets the action. This method can be chained.<br /><br />
+        
+        This method sets [page:.paused paused] to false, [page:.enabled enabled] to true, 
+        [page:.time time] to 0, interrupts any scheduled fading and warping, and removes the internal 
+        loop count and scheduling for delayed starting.<br /><br />
+
+        Note: .*reset* is always called by [page:.stop stop], but .*reset* doesn’t call .*stop* itself.
+        This means: If you want both, resetting and stopping, don’t call .*reset*; call .*stop* instead.
+    </div>
 
-    <h3>[method:AnimationAction stopFading]()</h3>
+    <h3>[method:AnimationAction setDuration]( [page:Number durationInSeconds] )</h3>
+    <div>
+        Sets the duration for a single loop of this action (by adjusting [page:.timeScale timeScale] 
+        and stopping any scheduled warping). This method can be chained.
+    </div>
 
     <h3>[method:AnimationAction setEffectiveTimeScale]( [page:Number timeScale] )</h3>
+    <div>
+        Sets the [page:.timeScale timeScale] and stops any scheduled warping. This method can be chained.<br /><br />
+        
+        If [page:.paused paused] is false, the effective time scale (an internal property) will also be set 
+        to this value; otherwise the effective time scale (directly affecting the animation at 
+        this moment) will be set to 0.<br /><br />
+        
+        Note: .*paused* will not be switched to *true* automatically, if .*timeScale* is set to 0 by 
+        this method.
+    </div>    
 
-    <h3>[method:Number getEffectiveTimeScale]()</h3>
-
-    <h3>[method:AnimationAction setDuration]( [page:Number duration] )</h3>
-
-    <h3>[method:AnimationAction syncWith]( [page:AnimationAction action] )</h3>
-
-    <h3>[method:AnimationAction halt]( [page:Number duration] )</h3>
-
-    <h3>[method:AnimationAction warp]( [page:Number startTimeScale], [page:Number endTimeScale], [page:Number duration] )</h3>
-
-    <h3>[method:AnimationAction stopWarping]()</h3>
-
-    <h3>[method:AnimationMixer getMixer]()</h3>
-
-    <h3>[method:AnimationClip getClip]()</h3>
-
-    <h3>[method:Object3D getRoot]()</h3>
-
-
-    <h2>Static Methods</h2>
+    <h3>[method:AnimationAction setEffectiveWeight]( [page:Number weight] )</h3>
+    <div>
+        Sets the [page:.weight weight] and stops any scheduled fading. This method can be chained.<br /><br />
+ 
+        If [page:.enabled enabled] is true, the effective weight (an internal property) will also be set 
+        to this value; otherwise the effective weight (directly affecting the animation at this moment) 
+        will be set to 0.<br /><br />
+
+        Note: .*enabled* will not be switched to *false* automatically, if .*weight* is set to 0 by 
+        this method.
+    </div>
+    
+    <h3>[method:AnimationAction setLoop]( [page:Number loopMode], [page:Number repetitions] )</h3>
+    <div>
+        Sets the [page:.loop loop mode] and the number of [page:.repetitions repetitions]. This method 
+        can be chained.
+    </div>  
 
+    <h3>[method:AnimationAction startAt]( [page:Number startTimeInSeconds] )</h3>
+    <div>
+        Defines the time for a delayed start (usually passed as [page:AnimationMixer.time] + 
+        deltaTimeInSeconds). This method can be chained.<br /><br />
+        
+        Note: The animation will only start at the given time, if .*startAt* is chained with 
+        [page:.play play], or if the action has already been activated in the mixer (by a previous 
+        call of .*play*, without stopping or resetting it in the meantime).
+    </div>
 
-    <h3>[method:AnimationClip parse]( [page:Object json] )</h3>
+    <h3>[method:AnimationAction stop]()</h3>
+    <div>
+        Tells the mixer to deactivate this action. This method can be chained.<br /><br />
+        
+        The action will be immediately stopped and completely [page:.reset reset].<br /><br />
+        
+        Note: You can stop all active actions on the same mixer in one go via 
+        [page:AnimationMixer.stopAllAction mixer.stopAllAction].
+    </div>
+    
+    <h3>[method:AnimationAction stopFading]()</h3>
     <div>
-    json -- JSON object
+        Stops any scheduled [page:.fadeIn fading] which is applied to this action. This method can be 
+        chained.
     </div>
 
-    <h3>[method:Object toJSON]( [page:AnimationClip clip] )</h3>
+    <h3>[method:AnimationAction stopWarping]()</h3>
     <div>
-    clip -- AnimationClip
+        Stops any scheduled [page:.warp warping] which is applied to this action. This method can be 
+        chained.
     </div>
 
-    <h3>[method:AnimationClip CreateFromMorphTargetSequence]( [page:String name], [page:Array morphTargetSequence], [page:Number fps], [page:Boolean noLoop] )</h3>
+    <h3>[method:AnimationAction syncWith]( [page:AnimationAction otherAction] )</h3>
     <div>
-    name -- Name for the new clip <br />
-    morphTargetSequence -- Array of morph targets <br />
-    fps -- Number of frames per second <br />
-    noLoop -- Whether looping occurs automatically.
+        Synchronizes this action with the passed other action. This method can be chained.<br /><br />
+        
+        Synchronizing is done by setting this action’s [page:.time time] and [page:.timeScale timeScale] values 
+        to the corresponding values of the other action (stopping any scheduled warping).<br /><br />
+
+        Note: Future changes of the other action's *time* and *timeScale* will not be detected.
     </div>
 
-    <h3>[method:AnimationClip parseAnimation]( [page:Object animation], [page:Array bones] )</h3>
+    <h3>[method:AnimationAction warp]( [page:Number startTimeScale], [page:Number endTimeScale], [page:Number durationInSeconds] )</h3>
     <div>
-    Parses the animation.hierarchy format and returns an AnimationClip.
+        Changes the playback speed, within the passed time interval, by modifying 
+        [page:.timeScale timeScale] gradually from *startTimeScale* to *endTimeScale*. This method can 
+        be chained.
     </div>
 
 
-    <h2>Source</h2>
+    <h2>Events</h2>
+    
+    
+    <div class="desc">
+        There are two events indicating when a single loop of the action respectively the entire action has finished. You can react to them with:
+    </div>
+    <code>
+mixer.addEventListener( 'loop', function( e ) { …} ); // properties of e: type, action and loopDelta        
+mixer.addEventListener( 'finished', function( e ) { …} ); // properties of e: type, action and direction
+    </code>    
 
+    <h2>Source</h2>
 
     [link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
   </body>

docs/api/animation/AnimationClip.html

@@ -11,73 +11,122 @@
     <h1>[name]</h1>
 
     <div class="desc">
-    An AnimationClip is a reusable set of Tracks that represent an animation.
+    An AnimationClip is a reusable set of keyframe tracks which represent an animation.<br /><br />
+    
+    For an overview of the different elements of the three.js animation system see the
+    "Animation System" article in the "Next Steps" section of the manual.
     </div>
-
+    
 
     <h2>Constructor</h2>
-
-
-    <h3>[name]( [page:String name], [page:Number duration], tracks )</h3>
-
-
+    
+    
+    <h3>[name]( [page:String name], [page:Number duration], [page:Array tracks] )</h3>
+    <div>
+        [page:String name] - a name for this clip.<br />
+        [page:Number duration] - the duration of this clip (in seconds). If a negative value is passed,
+        the duration will be calculated from the passed *tracks* array.<br />
+        [page:Array tracks] - an array of [page:KeyframeTrack KeyframeTracks].<br /><br />
+    
+        Note: Instead of instantiating an AnimationClip directly with the constructor, you can use one 
+        of its static methods to create AnimationClips: from JSON ([page:.parse parse]), from morph 
+        target sequences ([page:.CreateFromMorphTargetSequence CreateFromMorphTargetSequence],
+        [page:.CreateClipsFromMorphTargetSequences CreateClipsFromMorphTargetSequences]) or from 
+        animation hierarchies ([page:.parseAnimation parseAnimation]) - if your model doesn't already 
+        hold AnimationClips in its geometry's animations array.
+    </div>
+    
+    
     <h2>Properties</h2>
+    
 
-
-    <h3>[property:String uuid]</h3>
+    <h3>[property:Number duration]</h3>
+    <div>
+        The duration of this clip (in seconds). This can be calculated from the [page:.tracks tracks] 
+        array via [page:.resetDuration resetDuration].
+    </div>     
 
     <h3>[property:String name]</h3>
+    <div>
+        A name for this clip. A certain clip can be searched via [page:.findByName findByName].
+    </div>    
 
-    <h3>[property:Number duration]</h3>
-
-    <h3>.tracks</h3>
+    <h3>[property:Array tracks]</h3>
+    <div>
+        An array containing a [page:KeyframeTrack] for each property that are animated by this clip.
+    </div> 
 
+    <h3>[property:String uuid]</h3>
+    <div>
+        The [link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this clip instance.
+        It gets automatically assigned and shouldn't be edited.
+    </div>
+       
 
     <h2>Methods</h2>
 
 
-    <h3>[method:null resetDuration]()</h3>
+    <h3>[method:AnimationClip optimize]()</h3>
     <div>
-    Resets duration by scanning all tracks in the clip.
+        Optimizes each track by removing equivalent sequential keys (which are common in morph target 
+        sequences).
     </div>
 
-    <h3>[method:AnimationClip trim]()</h3>
+    <h3>[method:null resetDuration]()</h3>
     <div>
-    Trims all tracks to the clip's duration.
+        Sets the [page:.duration duration] of the clip to the duration of its longest 
+        [page:KeyframeTrack].
     </div>
 
-    <h3>[method:AnimationClip optimize]()</h3>
+    <h3>[method:AnimationClip trim]()</h3>
     <div>
-    Optimizes each track.
+        Trims all tracks to the clip's duration.
     </div>
 
 
     <h2>Static Methods</h2>
 
 
-    <h3>[method:AnimationClip parse]( [page:Object json] )</h3>
+    <h3>[method:Array CreateClipsFromMorphTargetSequences]( [page:String name], [page:Array morphTargetSequence], [page:Number fps], [page:Boolean noLoop] )</h3>
     <div>
-    json -- JSON object
+        Returns an array of new AnimationClips created from the [page:Geometry.morphTargets morph 
+        target sequences] of a geometry, trying to sort morph target names into animation-group-based 
+        patterns like "Walk_001, Walk_002, Run_001, Run_002 ..."<br /><br />
+        
+        This method is called by the [page:JSONLoader] internally, and it uses 
+        [page:.CreateFromMorphTargetSequence CreateFromMorphTargetSequence].
     </div>
 
-    <h3>[method:Object toJSON]( [page:AnimationClip clip] )</h3>
+    <h3>[method:AnimationClip CreateFromMorphTargetSequence]( [page:String name], [page:Array morphTargetSequence], [page:Number fps], [page:Boolean noLoop] )</h3>
     <div>
-    clip -- AnimationClip
-    </div>
+        Returns a new AnimationClip from the passed [page:Geometry.morphTargets morph targets array] 
+        of a geometry, taking a name and the number of frames per second.<br /><br />
 
-    <h3>[method:AnimationClip CreateFromMorphTargetSequence]( [page:String name], [page:Array morphTargetSequence], [page:Number fps], [page:Boolean noLoop] )</h3>
+        Note: The fps parameter is required, but the animation speed can be overridden in an 
+        *AnimationAction* via [page:AnimationAction.setDuration animationAction.setDuration].
+    </div>
+    
+    <h3>[method:AnimationClip findByName]( [page:Object objectOrClipArray], [page:String name] )</h3>
     <div>
-    name -- Name for the new clip <br />
-    morphTargetSequence -- Array of morph targets <br />
-    fps -- Number of frames per second <br />
-    noLoop -- Whether looping occurs automatically.
+        Searches for an AnimationClip by name, taking as its first parameter either an array of 
+        AnimationClips, or a mesh or geometry that contains an array named "animations".  
     </div>
 
-    <h3>[method:AnimationClip parseAnimation]( [page:Object animation], [page:Array bones] )</h3>
+    <h3>[method:AnimationClip parse]( [page:Object json] )</h3>
     <div>
-    Parses the animation.hierarchy format and returns an AnimationClip.
+        Parses a JSON representation of a clip and returns an AnimationClip.
     </div>
+    
+    <h3>[method:AnimationClip parseAnimation]( [page:Object animation], [page:Array bones] )</h3>
+    <div>
+        Parses the animation.hierarchy format and returns an AnimationClip.
+    </div>    
 
+    <h3>[method:Object toJSON]( [page:AnimationClip clip] )</h3>
+    <div>
+        Takes an AnimationClip and returns a JSON object.
+    </div>
+    
 
     <h2>Source</h2>
 

docs/api/animation/AnimationMixer.html

@@ -10,145 +10,102 @@
 	<body>
 		<h1>[name]</h1>
 
-		<div class="desc">
-		The AnimationMixer is a player for animations on a particular object in the scene.
-		</div>
-
-		<p>
-		Each available animation sequence is stored as an [page:AnimationClip AnimationClip], and
-		playback of that clip is controlled with an [page:AnimationClip AnimationAction]. When multiple
-		objects in the scene are animated independently, one AnimationMixer may be used for each object.
-		</p>
-
-		<h2>Example</h2>
-
-		<p>
-		When loading a 3D model that includes animation, many loaders also return a list of
-		[page:AnimationClip AnimationClip] instances. Each clip represents a specific animation
-		sequence, and may be played or paused individually.
-		</p>
-
-		<code>
-		var mesh;
-
-		// Create an AnimationMixer, and get the list of AnimationClip instances
-		var mixer = new THREE.AnimationMixer( mesh );
-		var clips = mesh.animations;
-
-		// Update the mixer on each frame
-		function update () {
-			mixer.update( deltaSeconds );
-		}
-
-		// Play a specific animation
-		var clip = THREE.AnimationClip.findByName( clips, 'dance' );
-		var action = mixer.clipAction(clip);
-		action.play();
-
-		// Play all animations
-		clips.forEach( function (clip) {
-			mixer.clipAction(clip).play();
-		} );
-		</code>
-
-		<p>
-		Note that not all model formats include animation (OBJ notably does not), and that only some
-		THREE.js loaders support [page:AnimationClip AnimationClip] sequences. Several that <i>do</i>
-		support this animation type:
-		</p>
-
-		<ul>
-			<li>[page:ObjectLoader THREE.ObjectLoader]</li>
-			<li>THREE.BVHLoader</li>
-			<li>THREE.FBXLoader</li>
-			<li>THREE.FBXLoader2</li>
-			<li>[page:GLTFLoader THREE.GLTFLoader]</li>
-			<li>THREE.MMDLoader</li>
-			<li>THREE.SEA3DLoader</li>
-		</ul>
-
-		<h2>Constructor</h2>
-
-
-		<h3>[name]( [page:Object3D root] )</h3>
-
-
-		<h2>Properties</h2>
-
-
-		<h3>[property:Number time]</h3>
-
-		<h3>[property:Number timeScale]</h3>
-
-
-		<h2>Methods</h2>
-
-
-		<h3>[method:AnimationAction clipAction]([page:AnimationClip clip], [page:Object3D optionalRoot])</h3>
-		<div>
-		clip -- AnimationClip <br />
-		optionalRoot -- Object3D
-		</div>
-		<div>
-		Return an action for a clip, optionally using a custom root target object.
-		</div>
-
-		<h3>[method:AnimationAction existingAction]([page:AnimationClip clip], [page:Object3D optionalRoot])</h3>
-		<div>
-		clip -- AnimationClip <br />
-		optionalRoot -- Object3D
-		</div>
-		<div>
-		Return an existing action.
-		</div>
-
-		<h3>[method:AnimationMixer stopAllAction]()</h3>
-		<div>
-		Deactivates all scheduled actions.
-		</div>
-
-		<h3>[method:AnimationMixer update]([page:Number deltaTimeMS]) </h3>
-		<div>
-		deltaTimeMS -- Time elapsed since last update in milliseconds.
-		</div>
-		<div>
-		Updates the animation with deltaTimeMS.
-		</div>
-
-		<h3>[method:Object3D getRoot]()</h3>
-		<div>
-		Return this mixer's root target object.
-		</div>
-
-		<h3>[method:null uncacheClip]([page:AnimationClip clip])</h3>
-		<div>
-		clip -- AnimationClip
-		</div>
-		<div>
-		Free all resources for a clip.
-		</div>
-
-		<h3>[method:null uncacheRoot]([page:Object3D root]) </h3>
-		<div>
-		root -- Object3D
-		</div>
-		<div>
-		Free all resources for a root target object.
-		</div>
-
-		<h3>[method:null uncacheAction]([page:AnimationClip clip], [page:Object3D optionalRoot])</h3>
-		<div>
-		clip -- AnimationClip <br />
-		optionalRoot -- Object3D
-		</div>
-		<div>
-		Free all resources for an action.
-		</div>
-
-
-		<h2>Source</h2>
-
-
-		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
+	<div class="desc">
+		The AnimationMixer is a player for animations on a particular object in the scene. When 
+        multiple objects in the scene are animated independently, one AnimationMixer may be used for 
+        each object.<br /><br />
+        		
+        For an overview of the different elements of the three.js animation system see the
+        "Animation System" article in the "Next Steps" section of the manual.
+    </div>
+
+
+    <h2>Constructor</h2>
+    
+
+    <h3>[name]( [page:Object3D rootObject] )</h3>
+    <div>
+        [page:Object3D rootObject] - the object whose animations shall be played by this mixer.<br />
+    </div>
+    
+   
+    <h2>Properties</h2>
+
+
+    <h3>[property:Number time]</h3>
+    <div>
+        The global mixer time (in seconds; starting with 0 on the mixer's creation).
+    </div>
+      
+    <h3>[property:Number timeScale]</h3>
+    <div>
+        A scaling factor for the global [page:.time mixer time].<br /><br />
+        
+        Note: Setting the mixer's timeScale to 0 and later back to 1 is a possibility to pause/unpause 
+        all actions that are controlled by this mixer.
+    </div>
+    
+
+    <h2>Methods</h2>
+
+
+    <h3>[method:AnimationAction clipAction]([page:AnimationClip clip], [page:Object3D optionalRoot])</h3>
+    <div>
+        Returns an [page:AnimationAction] for the passed clip, optionally using a root object different 
+        from the mixer's default root. The first parameter can be either an [page:AnimationClip] object 
+        or the name of an AnimationClip.<br /><br />
+        
+        If an action fitting these parameters doesn't yet exist, it will be created by this method.<br /><br />
+ 
+        Note: Calling this method several times with the same parameters returns always the same clip 
+        instance.
+    </div>
+
+    <h3>[method:AnimationAction existingAction]([page:AnimationClip clip], [page:Object3D optionalRoot])</h3>
+    <div>
+        Returns an existing [page:AnimationAction] for the passed clip, optionally using a root object
+        different from the mixer's default root.<br /><br />
+        
+        The first parameter can be either an [page:AnimationClip] object or the name of an AnimationClip.
+    </div>
+
+    <h3>[method:AnimationMixer stopAllAction]()</h3>
+    <div>
+        Deactivates all previously scheduled actions on this mixer.
+    </div>
+
+    <h3>[method:AnimationMixer update]([page:Number deltaTimeInSeconds]) </h3>
+    <div>
+        Advances the global mixer time and updates the animation.<br /><br />
+         
+        This is usually done in the render loop, passing [page:Clock.getDelta clock.getDelta] scaled by the mixer's [page:.timeScale timeScale]).
+    </div>
+
+    <h3>[method:Object3D getRoot]()</h3>
+    <div>
+        Returns this mixer's root object.
+    </div>
+
+    <h3>[method:null uncacheClip]([page:AnimationClip clip])</h3>
+
+    <div>
+        Deallocates all memory resources for a clip.
+    </div>
+
+    <h3>[method:null uncacheRoot]([page:Object3D root]) </h3>
+    <div>
+        Deallocates all memory resources for a root object.
+    </div>
+
+    <h3>[method:null uncacheAction]([page:AnimationClip clip], [page:Object3D optionalRoot])</h3>
+    <div>
+        Deallocates all memory resources for an action.
+    </div>
+
+
+    <h2>Source</h2>
+
+
+    [link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
 	</body>
 </html>

docs/api/animation/AnimationObjectGroup.html

@@ -10,24 +10,28 @@
   <body>
     <h1>[name]</h1>
 
-    <div class="desc">A group of objects that receives a shared animation state.</div>
+    <div class="desc">A group of objects that receives a shared animation state.<br /><br />
+        		
+        For an overview of the different elements of the three.js animation system see the
+        "Animation System" article in the "Next Steps" section of the manual.
+    </div>
 
     <h2>Usage:</h2>
 
-    <div>
-      Add objects you would otherwise pass as 'root' to the	constructor or the [page:AnimationMixer.clipAction clipAction]
-      method of [page:AnimationMixer AnimationMixer] and instead pass this object as 'root'.<br /><br />
+    <div class="desc">
+        Add objects you would otherwise pass as 'root' to the	constructor or the [page:AnimationMixer.clipAction clipAction]
+        method of [page:AnimationMixer AnimationMixer] and instead pass this object as 'root'.<br /><br />
 
-      Note that objects of this class appear as one object to the mixer,
-      so cache control of the individual objects must be done	on the group.
+        Note that objects of this class appear as one object to the mixer,
+        so cache control of the individual objects must be done	on the group.
     </div>
 
 
-   <h2>Limitations</h2>
-   <div>
-    The animated properties must be compatible among all objects in the group.<br /><br />
+    <h2>Limitations</h2>
+    <div class="desc">
+        The animated properties must be compatible among all objects in the group.<br /><br />
 
-    A single property can either be controlled through a target group or directly, but not both.
+        A single property can either be controlled through a target group or directly, but not both.
     </div>
 
 
@@ -35,34 +39,41 @@
 
 
     <h3>[name]( [page:object obj1], [page:object obj2], [page:object obj3], ... )</h3>
+      [page:object obj] - an abitrary number of meshes that share the same animation state.<br />
 
-
+   
     <h2>Properties</h2>
+    
 
     <h3>[property:object stats]</h3>
     <div>
-
+        An object that contains some informations of this *AnimationObjectGroup* (total number, number 
+        in use, number of bindings per object)
+    </div>    
+    
+    <h3>[property:String uuid]</h3>
+    <div>
+        The [link:http://en.wikipedia.org/wiki/Universally_unique_identifier UUID] of this 
+        *AnimationObjectGroup*. It gets automatically assigned and shouldn't be edited.
     </div>
 
-    <h3>[property:Number timeScale]</h3>
-
 
     <h2>Methods</h2>
 
 
     <h3>[method:null add]( [page:object obj1], [page:object obj2], [page:object obj3], ... )</h3>
     <div>
-
+        Adds an arbitrary number of objects to this *AnimationObjectGroup*.
     </div>
 
     <h3>[method:null remove]( [page:object obj1], [page:object obj2], [page:object obj3], ... )</h3>
     <div>
-
+        Removes an arbitrary number of objects from this *AnimationObjectGroup*.
     </div>
 
     <h3>[method:null uncache]( [page:object obj1], [page:object obj2], [page:object obj3], ... )</h3>
     <div>
-
+        Deallocates all memory resources for the passed objects of this *AnimationObjectGroup*.
     </div>
 
 

docs/api/animation/AnimationUtils.html

@@ -11,10 +11,12 @@
     <h1>[name]</h1>
 
     <div class="desc">
-    An object with various functions to assist with animations.
+    An object with various functions to assist with animations, used internally.
     </div>
+    
 
     <h2>Methods</h2>
+    
 
     <h3>[method:Array arraySlice]( array, from, to )</h3>
     <div>
@@ -23,12 +25,12 @@
 
     <h3>[method:Array convertArray]( array, type, forceClone )</h3>
     <div>
-    Convert an array to a specific type.
+    Converts an array to a specific type.
     </div>
 
-    <h3>[method:Boolean isTypedArray]( object )</h3>
+    <h3>[method:Array flattenJSON]( jsonKeys, times, values, valuePropertyName  )</h3>
     <div>
-    Return *true* if the object is a typed array.
+    Used for parsing AOS keyframe formats.
     </div>
 
     <h3>[method:Array getKeyframeOrder]( times )</h3>
@@ -36,15 +38,16 @@
     Returns an array by which times and values can be sorted.
     </div>
 
-    <h3>[method:Array sortedArray]( values, stride, order )</h3>
+    <h3>[method:Boolean isTypedArray]( object )</h3>
     <div>
-    Sort the array previously returned by [page:AnimationUtils.getKeyframeOrder getKeyframeOrder].
+    Returns *true* if the object is a typed array.
     </div>
 
-    <h3>[method:Array flattenJSON]( jsonKeys, times, values, valuePropertyName  )</h3>
+    <h3>[method:Array sortedArray]( values, stride, order )</h3>
     <div>
-    Used for parsing AOS keyframe formats
+    Sorts the array previously returned by [page:AnimationUtils.getKeyframeOrder getKeyframeOrder].
     </div>
+    
 
     <h2>Source</h2>
 

docs/api/animation/KeyframeTrack.html

@@ -12,8 +12,49 @@
     <h1>[name]</h1>
 
     <div class="desc">
-    A timed sequence of [link:https://en.wikipedia.org/wiki/Key_frame keyframes] for animating
-    a specific property of an object.
+        A KeyframeTrack is a timed sequence of [link:https://en.wikipedia.org/wiki/Key_frame keyframes], 
+        which are composed of lists of times and related values, and which are used to animate a 
+        specific property of an object.<br /><br />
+
+        For an overview of the different elements of the three.js animation system see the
+        "Animation System" article in the "Next Steps" section of the manual.<br /><br />
+
+        In contrast to the animation hierarchy of the 
+        [link:https://github.com/mrdoob/three.js/wiki/JSON-Model-format-3 JSON model format] a 
+        *KeyframeTrack* doesn't store its single keyframes as objects in a "keys" array (holding the 
+        times and the values for each frame together in one place).<br /><br />
+         
+        Instead of this there are always two arrays in a *KeyframeTrack*: the [page:.times times] array 
+        stores the time values for all keyframes of this track in sequential order, and the 
+        [page:.values values] array contains the corresponding changing values of the animated property.<br /><br />
+         
+        A single value, belonging to a certain point of time, can not only be a simple number, but (for 
+        example) a vector (if a position is animated) or a quaternion (if a rotation is animated). For 
+        this reason the values array (which is a flat array, too) might be three or four times as long as the 
+        times array.<br /><br />
+
+        Corresponding to the different possible types of animated values there are several subclasses of 
+        *KeyframeTrack*, inheriting the most properties and methods:
+        
+        <ul> 
+            <li>[page:BooleanKeyframeTrack]</li> 
+            <li>[page:ColorKeyframeTrack]</li>
+            <li>[page:NumberKeyframeTrack]</li>
+            <li>[page:QuaternionKeyframeTrack]</li>
+            <li>[page:StringKeyframeTrack]</li> 
+            <li>[page:VectorKeyframeTrack]</li>
+        </ul>
+        Some examples of how to manually create [page:AnimationClip AnimationClips] with different sorts 
+        of KeyframeTracks can be found in the [link:https://threejs.org/examples/js/AnimationClipCreator.js] 
+        file.<br /><br />
+
+        Since explicit values are only specified for the discrete points of time stored in the times array, 
+        all values in between have to be interpolated.<br /><br />
+        
+        The track's name is important for the connection of this track with a specific property of the 
+        animated node (done by [page:PropertyBinding]).
+    
+
     </div>
 
 
@@ -22,129 +63,171 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values], [page:Constant interpolation] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
-      -- [page:Constant interpolation] the type of interpolation to use. See [page:Animation Animation Constants] for possible values.
-      Default is [page:Animation InterpolateLinear].
+      [page:String name] - the identifier for the *KeyframeTrack*.<br />
+      [page:Array times] - an array of keyframe times, converted internally to a 
+      [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array].<br />
+      [page:Array values] - an array with the values related to the times array, converted internally to a 
+      [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array].<br />
+      [page:Constant interpolation] - the type of interpolation to use. See 
+      [page:Animation Animation Constants] for possible values. Default is [page:Animation InterpolateLinear].
     </div>
+    
 
     <h2>Properties</h2>
 
 
     <h3>[property:String name]</h3>
     <div>
-    The name given to the KeyframeTrack in the constructor.
+        The track's name can refer to [page:Geometry.morphTargets morph targets] or 
+        [page:SkinnedMesh bones] or possibly other values within an animated object. See 
+        [page:PropertyBinding.parseTrackName] for the forms of strings that can be parsed for property 
+        binding:<br /><br />
+
+        The name can specify the node either using its name or its uuid (although it needs to be in the 
+        subtree of the scene graph node passed into the mixer). Or, if the track name starts with a dot, 
+        the track applies to the root node that was passed into the mixer.<br /><br />
+
+        Usually after the node a property will be specified directly. But you can also specify a 
+        subproperty, such as .rotation[x], if you just want to drive the X component of the rotation 
+        via a float track.<br /><br />
+
+        You can also specify bones or multimaterials by using an object name, for example: 
+        .bones[R_hand].scale; the red channel of the diffuse color of the fourth material in a 
+        materials array - as a further example - can be accessed with .materials[3].diffuse[r].<br /><br />
+
+        PropertyBinding will also resolve morph target names, for example: .morphTargetInfluences[run].<br /><br />
+
+        Note: The track's name does not necessarily have to be unique. Multiple tracks can drive the same 
+        property. The result should be based on a weighted blend between the multiple tracks according to 
+        the weights of their respective actions.
     </div>
 
     <h3>[property:Float32Array times]</h3>
     <div>
-    [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array]
-    of keyframe times.
+        A [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array], 
+        converted from the times array which is passed in the constructor.
     </div>
 
     <h3>[property:Float32Array values]</h3>
     <div>
-    [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array]
-    of keyframe values, corresponding to the [page:KeyframeTrack.times times].
+        A [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array], 
+        converted from the values array which is passed in the constructor.
     </div>
 
     <h3>[property:Constant DefaultInterpolation]</h3>
     <div>
-    The default tnterpolation type to use, [page:Animation InterpolateLinear].
+        The default interpolation type: [page:Animation InterpolateLinear].
+    </div>    
+    
+    <h3>[property:Constant TimeBufferType ]</h3>
+    <div>
+        [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array],
+        the type of the buffer internally used for the times.
+    </div>    
+    
+    <h3>[property:Constant ValueBufferType ]</h3>
+    <div>
+        [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array],
+        the type of the buffer internally used for the values.
     </div>
 
 
     <h2>Methods</h2>
+    
 
-    <h3>[method:null createInterpolant ](  )</h3>
-    <div>
-      Create a [page:LinearInterpolant LinearInterpolant], [page:CubicInterpolant CubicInterpolant]
-      or [page:DiscreteInterpolant DiscreteInterpolant], depending on the value of the interpolation parameter
-      passed in the constructor.
-    </div>
-
-    <h3>[method:null getInterpolation ](  )</h3>
+    <h3>[method:null createInterpolant]()</h3>
     <div>
-      Get the interpolation type.
+      Creates a [page:LinearInterpolant LinearInterpolant], [page:CubicInterpolant CubicInterpolant]
+      or [page:DiscreteInterpolant DiscreteInterpolant], depending on the value of the interpolation 
+      parameter passed in the constructor.
     </div>
 
-    <h3>[method:Number getValueSize ](  )</h3>
+    <h3>[method:null getInterpolation]()</h3>
     <div>
-      The the size of each value (length of the values array divied by length of times array).
+      Returns the interpolation type.
     </div>
 
-    <h3>[method:DiscreteInterpolant InterpolantFactoryMethodDiscrete ]( result )</h3>
+    <h3>[method:Number getValueSize]()</h3>
     <div>
-      Create a new [page:DiscreteInterpolant DiscreteInterpolant] from the [page:KeyframeTrack.times times]
-      and [page:KeyframeTrack.times values].
+      Returns the size of each value (that is the length of the [page:.values values] array divided 
+      by the length of the [page:.times times] array).
     </div>
 
-    <h3>[method:null InterpolantFactoryMethodLinear ](  )</h3>
+    <h3>[method:DiscreteInterpolant InterpolantFactoryMethodDiscrete]( [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array result] )</h3>
     <div>
-      Create a new [page:LinearInterpolant LinearInterpolant] from the [page:KeyframeTrack.times times]
-      and [page:KeyframeTrack.times values].
+      Creates a new [page:DiscreteInterpolant DiscreteInterpolant] from the 
+      [page:KeyframeTrack.times times] and [page:KeyframeTrack.times values]. A Float32Array can be 
+      passed which will receive the results. Otherwise a new array with the appropriate size will be 
+      created automatically.
     </div>
 
-    <h3>[method:null InterpolantFactoryMethodSmooth ](  )</h3>
+    <h3>[method:null InterpolantFactoryMethodLinear]( [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array result] )</h3>
     <div>
-      Create a new [page:CubicInterpolant CubicInterpolant] from the [page:KeyframeTrack.times times]
-      and [page:KeyframeTrack.times values].
+      Creates a new [page:LinearInterpolant LinearInterpolant] from the 
+      [page:KeyframeTrack.times times] and [page:KeyframeTrack.times values]. A Float32Array can be 
+      passed which will receive the results. Otherwise a new array with the appropriate size will be 
+      created automatically.
     </div>
 
-    <h3>[method:null optimize ](  )</h3>
+    <h3>[method:null InterpolantFactoryMethodSmooth]( [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array result] )</h3>
     <div>
-      Remove equivalent sequential keys, which are common in morph target sequences. <br />
-  	  Called automatically by the constructor.
+      Create a new [page:CubicInterpolant CubicInterpolant] from the 
+      [page:KeyframeTrack.times times] and [page:KeyframeTrack.times values]. A Float32Array can be 
+      passed which will receive the results. Otherwise a new array with the appropriate size will be 
+      created automatically.
     </div>
 
-    <h3>[method:KeyframeTrack parse]( [page:JSON json] )</h3>
+    <h3>[method:null optimize]()</h3>
     <div>
-    Parse json and return new keyframe track of the correct type.
+      Removes equivalent sequential keys, which are common in morph target sequences. Called 
+      automatically by the constructor.
     </div>
 
-    <h3>[method:null scale ](  )</h3>
+    <h3>[method:null scale]()</h3>
     <div>
-      Scale all keyframe times by a factor (useful for frame <-> seconds conversions).
+      Scales all keyframe times by a factor.<br /><br />
+      
+      Note: This is useful, for example, for conversions to a certain rate of frames per seconds (as it
+      is done internally by 
+      [page:AnimationClip.CreateFromMorphTargetSequence animationClip.CreateFromMorphTargetSequence]).
     </div>
 
-    <h3>[method:null setInterpolation ]( [page:Constant interpolation] )</h3>
+    <h3>[method:null setInterpolation]( [page:Constant interpolationType] )</h3>
     <div>
-      Set the interpolation type. See [page:Animation animation constants] for choices.
+      Sets the interpolation type. See [page:Animation Animation Constants] for choices.
     </div>
 
-    <h3>[method:null shift ]( [page:Number timeOffset] )</h3>
+    <h3>[method:null shift]( [page:Number timeOffsetInSeconds] )</h3>
     <div>
-      Move all keyframes either forwards or backwards in time.
+      Moves all keyframes either forward or backward in time.
     </div>
 
-    <h3>[method:null TimeBufferType ](  )</h3>
-    <div>
-      [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array],
-      used to convert the times array passed in the constructor to a Float32Array.
-    </div>
 
-    <h3>[method:JSON toJSON]( [page:KeyframeTrack track] )</h3>
+    <h3>[method:null trim]( [page:Number startTimeInSeconds], [page:Number endTimeInSeconds] )</h3>
     <div>
-    Convert the track to JSON.
+      Removes keyframes before *startTime* and after *endTime*,
+      without changing any values within the range [*startTime*, *endTime*].
     </div>
 
-    <h3>[method:null trim ]( [page:Number startTime], [page:Number endTime] )</h3>
+    <h3>[method:null validate]()</h3>
     <div>
-      Removes keyframes before [page:Number startTime] and after [page:Number endTime]
-      without changing any values within the range [[page:Number startTime], [page:Number endTime]].
+      Performs minimal validation on the tracks. Called automatically by the constructor.<br /><br />
+      This method logs errors to the console, if a track is empty, if the [page:.valueSize value size] is not valid, if an item
+      in the [page:.times times] or [page:.values values] array is not a valid number or if the items in the *times* array are out of order. 
     </div>
+    
+    <h2>Static Methods</h2>
 
-    <h3>[method:null validate ](  )</h3>
+    <h3>[method:KeyframeTrack parse]( [page:JSON json] )</h3>
     <div>
-      Perform minimal validation on the tracks. Called automatically by the constructor.
-    </div>
+    Parses a JSON object and returns a new keyframe track of the correct type.
+    </div>    
 
-    <h3>[method:null ValueBufferType ](  )</h3>
+    <h3>[method:JSON toJSON]( [page:KeyframeTrack track] )</h3>
     <div>
-      [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array Float32Array],
-      used to convert the values array passed in the constructor to a Float32Array.
+    Converts the track to JSON.
     </div>
+    
 
     <h2>Source</h2>
 

docs/api/animation/PropertyBinding.html

@@ -11,7 +11,7 @@
     <h1>[name]</h1>
 
     <div class="desc">
-    This holds a reference to a real property in the scene graph.
+    This holds a reference to a real property in the scene graph; used internally.
     </div>
 
 

docs/api/animation/PropertyMixer.html

@@ -11,7 +11,7 @@
     <h1>[name]</h1>
 
     <div class="desc">
-    Buffered scene graph property that allows weighted accumulation.
+    Buffered scene graph property that allows weighted accumulation; used internally.
     </div>
 
 

docs/api/animation/tracks/BooleanKeyframeTrack.html

@@ -9,12 +9,12 @@
   </head>
   <body>
 
-		[page:KeyframeTrack] &rarr;
+	[page:KeyframeTrack] &rarr;
 
     <h1>[name]</h1>
 
     <div class="desc">
-     A Track of Boolean keyframe values.
+     A Track of boolean keyframe values.
     </div>
 
 
@@ -23,19 +23,17 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
+      [page:String name] - (required) identifier for the KeyframeTrack.<br />
+      [page:Array times] - (required) array of keyframe times.<br />
+      [page:Array values] - values for the keyframes at the times specified.<br />
     </div>
+    
 
     <h2>Properties</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited properties.
-
-
-    <h3>[property:String ValueTypeName]</h3>
-    <div>
-    String 'bool'.
     </div>
 
     <h3>[property:Constant DefaultInterpolation]</h3>
@@ -43,27 +41,35 @@
     The default interpolation type to use, [page:Animation InterpolateDiscrete].
     </div>
 
+    <h3>[property:Array ValueBufferType]</h3>
+    <div>
+        A normal Array (no Float32Array in this case, unlike *ValueBufferType* of [page:KeyframeTrack]).
+    </div>
 
-    <h2>Methods</h2>
-
-		See [page:KeyframeTrack] for inherited methods.
-
-    <h3>[method:null InterpolantFactoryMethodLinear ](  )</h3>
+    <h3>[property:String ValueTypeName]</h3>
     <div>
-      The value of this method here is 'undefined', as it does not make sense for discrete properties.
+        String 'bool'.
     </div>
+    
 
-    <h3>[method:null InterpolantFactoryMethodSmooth ](  )</h3>
+    <h2>Methods</h2>
+    
+    
+    <div class="desc">
+		See [page:KeyframeTrack] for inherited methods.
+    </div>
+    
+    <h3>[method:null InterpolantFactoryMethodLinear ]()</h3>
     <div>
-      The value of this method here is 'undefined', as it does not make sense for discrete properties.
+        The value of this method here is 'undefined', as it does not make sense for discrete properties.
     </div>
 
-    <h3>[method:null ValueBufferType ](  )</h3>
+    <h3>[method:null InterpolantFactoryMethodSmooth ]()</h3>
     <div>
-      Used to convert the values array passed in the constructor to an Array.
-			Note: In this case this does nothing, other Track types may convert the array to a Typed Array.
+        The value of this method here is 'undefined', as it does not make sense for discrete properties.
     </div>
 
+
     <h2>Source</h2>
 
 

docs/api/animation/tracks/ColorKeyframeTrack.html

@@ -9,12 +9,14 @@
   </head>
   <body>
 
-		[page:KeyframeTrack] &rarr;
+    [page:KeyframeTrack] &rarr;
 
     <h1>[name]</h1>
 
     <div class="desc">
-     A Track of keyframe values that represent color.
+        A Track of keyframe values that represent color changes.<br /><br />
+        The very basic implementation of this subclass has nothing special yet. However, this is the place 
+        for color space parameterization.
     </div>
 
 
@@ -23,26 +25,34 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
-			-- [page:Constant interpolation] the type of interpolation to use. See [page:Animation Animation Constants] for possible values.
-      Default is [page:Animation InterpolateLinear].
+        [page:String name] - (required) identifier for the KeyframeTrack.<br />
+        [page:Array times] - (required) array of keyframe times.<br />
+        [page:Array values] - values for the keyframes at the times specified.<br />
+        [page:Constant interpolation] - the type of interpolation to use. See 
+        [page:Animation Animation Constants] for possible values. Default is 
+        [page:Animation InterpolateLinear].
     </div>
+    
 
     <h2>Properties</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited properties.
-
+    </div>
+    
     <h3>[property:String ValueTypeName]</h3>
     <div>
-    String 'color'.
+        String 'color'.
     </div>
+    
 
     <h2>Methods</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited methods.
-
+    </div>
 
     <h2>Source</h2>
 

docs/api/animation/tracks/NumberKeyframeTrack.html

@@ -9,12 +9,12 @@
   </head>
   <body>
 
-		[page:KeyframeTrack] &rarr;
+    [page:KeyframeTrack] &rarr;
 
     <h1>[name]</h1>
 
     <div class="desc">
-     A Track of numeric keyframe values.
+        A Track of numeric keyframe values.
     </div>
 
 
@@ -23,26 +23,36 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
-			-- [page:Constant interpolation] the type of interpolation to use. See [page:Animation Animation Constants] for possible values.
-      Default is [page:Animation InterpolateLinear].
+        [page:String name] - (required) identifier for the KeyframeTrack.<br />
+        [page:Array times] - (required) array of keyframe times.<br />
+        [page:Array values] - values for the keyframes at the times specified.<br />
+        [page:Constant interpolation] - the type of interpolation to use. See 
+        [page:Animation Animation Constants] for possible values. Default is 
+        [page:Animation InterpolateLinear].
     </div>
+    
 
     <h2>Properties</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited properties.
-
+    </div>
+    
 
     <h3>[property:String ValueTypeName]</h3>
     <div>
-    String 'number'.
+        String 'number'.
     </div>
+    
 
     <h2>Methods</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited methods.
+    </div>
+    
 
     <h2>Source</h2>
 

docs/api/animation/tracks/QuaternionKeyframeTrack.html

@@ -9,12 +9,12 @@
   </head>
   <body>
 
-		[page:KeyframeTrack] &rarr;
+    [page:KeyframeTrack] &rarr;
 
     <h1>[name]</h1>
 
     <div class="desc">
-     A Track of quaternion keyframe values.
+        A Track of quaternion keyframe values.
     </div>
 
 
@@ -23,46 +23,50 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
-			-- [page:Constant interpolation] the type of interpolation to use. See [page:Animation Animation Constants] for possible values.
-      Default is [page:Animation InterpolateLinear].
+        [page:String name] (required) identifier for the KeyframeTrack.<br />
+        [page:Array times] (required) array of keyframe times.<br />
+        [page:Array values] values for the keyframes at the times specified.<br />
+        [page:Constant interpolation] the type of interpolation to use. See 
+        [page:Animation Animation Constants] for possible values. Default is 
+        [page:Animation InterpolateLinear].
     </div>
+    
 
     <h2>Properties</h2>
+    
 
-		See [page:KeyframeTrack] for inherited properties.
-
+    <div class="desc">
+    	See [page:KeyframeTrack] for inherited properties.
+    </div>
 
-    <h3>[property:String ValueTypeName]</h3>
+    <h3>[property:Constant DefaultInterpolation]</h3>
     <div>
-    String 'quaternion'.
+        The default interpolation type to use, [page:Animation InterpolateLinear].
     </div>
 
-    <h3>[property:Constant DefaultInterpolation]</h3>
+    <h3>[property:String ValueTypeName]</h3>
     <div>
-    The default interpolation type to use, [page:Animation InterpolateLinear].
+        String 'quaternion'.
     </div>
 
 
     <h2>Methods</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited methods.
+    </div>    
 
-    <h3>[method:Number getValueSize ](  )</h3>
-    <div>
-      The the size of each value (length of the values array divied by length of times array).
-    </div>
-
-    <h3>[method:null InterpolantFactoryMethodLinear ](  )</h3>
+    <h3>[method:null InterpolantFactoryMethodLinear]()</h3>
     <div>
-      Returns a new [page:QuaternionLinearInterpolant QuaternionLinearInterpolant] based on the [page:KeyframeTrack.values values],
-			[page:KeyframeTrack.times times] and [page:KeyframeTrack.valueSize valueSize] of the keyframes.
+        Returns a new [page:QuaternionLinearInterpolant QuaternionLinearInterpolant] based on the 
+        [page:KeyframeTrack.values values], [page:KeyframeTrack.times times] and 
+        [page:KeyframeTrack.valueSize valueSize] of the keyframes.
     </div>
 
 
     <h2>Source</h2>
+    
 
     [link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
   </body>

docs/api/animation/tracks/StringKeyframeTrack.html

@@ -9,12 +9,12 @@
   </head>
   <body>
 
-		[page:KeyframeTrack] &rarr;
+	[page:KeyframeTrack] &rarr;
 
     <h1>[name]</h1>
 
     <div class="desc">
-     A Track of String keyframe values.
+        A Track of string keyframe values.
     </div>
 
 
@@ -23,48 +23,55 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
-			-- [page:Constant interpolation] the type of interpolation to use. See [page:Animation Animation Constants] for possible values.
-      Default is [page:Animation InterpolateDiscrete].
+        [page:String name] - (required) identifier for the KeyframeTrack.<br />
+        [page:Array times] - (required) array of keyframe times.<br />
+        [page:Array values] - values for the keyframes at the times specified.<br />
+        [page:Constant interpolation] - the type of interpolation to use. See 
+        [page:Animation Animation Constants] for possible values. Default is 
+        [page:Animation InterpolateDiscrete].
     </div>
+    
 
     <h2>Properties</h2>
+    
 
-		See [page:KeyframeTrack] for inherited properties.
+    <div class="desc">
+    	See [page:KeyframeTrack] for inherited properties.
+    </div>    
 
+    <h3>[property:Constant DefaultInterpolation]</h3>
+    <div>
+        The default interpolation type to use, [page:Animation InterpolateDiscrete].
+    </div>
 
-    <h3>[property:String ValueTypeName]</h3>
+    <h3>[property:Array ValueBufferType]</h3>
     <div>
-    String 'string'.
+        A normal Array (no Float32Array in this case, unlike *ValueBufferType* of [page:KeyframeTrack]).
     </div>
 
-    <h3>[property:Constant DefaultInterpolation]</h3>
+    <h3>[property:String ValueTypeName]</h3>
     <div>
-    The default interpolation type to use, [page:Animation InterpolateDiscrete].
+        String 'string'.
     </div>
 
 
     <h2>Methods</h2>
+    
 
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited methods.
+    </div>    
 
-    <h3>[method:null InterpolantFactoryMethodLinear ](  )</h3>
+    <h3>[method:null InterpolantFactoryMethodLinear]()</h3>
     <div>
       The value of this method here is 'undefined', as it does not make sense for discrete properties.
     </div>
 
-    <h3>[method:null InterpolantFactoryMethodSmooth ](  )</h3>
+    <h3>[method:null InterpolantFactoryMethodSmooth]()</h3>
     <div>
       The value of this method here is 'undefined', as it does not make sense for discrete properties.
     </div>
-
-    <h3>[method:null ValueBufferType ](  )</h3>
-    <div>
-      Used to convert the values array passed in the constructor to an Array.
-			Note: In this case this does nothing, other Track types may convert the array to a Typed Array.
-    </div>
+    
 
     <h2>Source</h2>
 

docs/api/animation/tracks/VectorKeyframeTrack.html

@@ -9,12 +9,12 @@
   </head>
   <body>
 
-		[page:KeyframeTrack] &rarr;
+    [page:KeyframeTrack] &rarr;
 
     <h1>[name]</h1>
 
     <div class="desc">
-     A Track of Vector keyframe values.
+        A Track of vector keyframe values.
     </div>
 
 
@@ -23,25 +23,35 @@
 
     <h3>[name]( [page:String name], [page:Array times], [page:Array values] )</h3>
     <div>
-      -- [page:String name] (required) identifier for the KeyframeTrack.<br />
-      -- [page:Array times] (required) array of keyframe times<br />
-      -- [page:Array values] values for the keyframes at the times specified.<br />
-			-- [page:Constant interpolation] the type of interpolation to use. See [page:Animation Animation Constants] for possible values.
-      Default is [page:Animation InterpolateLinear].
+        [page:String name] - (required) identifier for the KeyframeTrack.<br />
+        [page:Array times] - (required) array of keyframe times.<br />
+        [page:Array values] - values for the keyframes at the times specified.<br />
+        [page:Constant interpolation] - the type of interpolation to use. See 
+        [page:Animation Animation Constants] for possible values. Default is 
+        [page:Animation InterpolateLinear].
     </div>
+    
 
     <h2>Properties</h2>
+    
 
-		See [page:KeyframeTrack] for inherited properties.
+    <div class="desc">
+    	See [page:KeyframeTrack] for inherited properties.
+    </div>  
 
     <h3>[property:String ValueTypeName]</h3>
     <div>
-    String 'vector'.
+        String 'vector'.
     </div>
+    
 
     <h2>Methods</h2>
-
+    
+    
+    <div class="desc">
 		See [page:KeyframeTrack] for inherited methods.
+    </div>
+    
 
     <h2>Source</h2>
 

docs/list.js

@@ -14,8 +14,9 @@ var list = {
 		],
 
 		"Next Steps": [
-				[ "How to update things", "manual/introduction/How-to-update-things" ],
-			[ "Matrix transformations", "manual/introduction/Matrix-transformations" ]
+			[ "How to update things", "manual/introduction/How-to-update-things" ],
+			[ "Matrix transformations", "manual/introduction/Matrix-transformations" ],
+            [ "Animation System", "manual/introduction/Animation-system" ]
 		],
 
 		"Build Tools": [

docs/manual/introduction/Animation-system.html

@@ -0,0 +1,151 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+    <h1>[name]</h1>
+       
+    <h2>Overview</h2>
+
+    <div class="desc">
+        Within the three.js animation system you can animate various properties of your models:
+        the bones of a [page:SkinnedMesh skinned and rigged model], 
+        [page:Geometry.morphTargets morph targets], different material properties (colors, 
+        opacity, booleans), visibility and transforms. The animated properties can be faded in,
+        faded out, crossfaded and warped. The weight and time scales of different simultaneous 
+        animations on the same object as well as on different objects can be changed 
+        independently. Various animations on the same and on different objects can be 
+        synchronized.<br /><br />
+
+        To achieve all this in one homogeneous system, the three.js animation system
+        [link:https://github.com/mrdoob/three.js/issues/6881 has completely changed in 2015]
+        (be aware of outdated information!), and it has now an architecture similar to 
+        Unity/Unreal Engine 4. This page gives a short overview of the main components of the 
+        system and how they work together.
+        
+    </div>
+           
+    <h3>Animation Clips</h3>
+        
+    <div class="desc">        
+       
+        If you have successfully imported an animated 3D object (it doesn't matter if it has
+        bones or morph targets or both) - for example exporting it from Blender with the 
+        [link:https://github.com/mrdoob/three.js/tree/master/utils/exporters/blender/addons/io_three Blender exporter] and
+        loading it into a three.js scene using [page:JSONLoader] -, one of the geometry's 
+        properties of the loaded mesh should be an array named "animations", containing the 
+        [page:AnimationClip AnimationClips] for this model (see a list of possible loaders below).<br /><br />
+
+        Each *AnimationClip* usually holds the data for a certain activity of the object. If the 
+        mesh is a character, for example, there may be one AnimationClip for a walkcycle, a second 
+        for a jump, a third for sidestepping and so on.
+
+    </div>
+           
+    <h3>Keyframe Tracks</h3>
+        
+    <div class="desc">        
+       
+        Inside of such an *AnimationClip* the data for each animated property are stored in a 
+        separate [page:KeyframeTrack]. Assumed a character object has a [page:Skeleton skeleton],
+        one keyframe track could store the data for the position changes of the lower arm bone 
+        over time, a different track the data for the rotation changes of the same bone, a third 
+        the track position, rotation or scaling of another bone, and so on. It should be clear, 
+        that an AnimationClip can be composed of lots of such tracks.<br /><br />
+        
+        Assumed the model has [page:Geometry.morphTargets morph targets] (for example one morph 
+        target showing a friendly face and another showing an angry face), each track holds the 
+        information as to how the [page:Mesh.morphTargetInfluences influence] of a certain morph 
+        target changes during the performance of the clip.
+
+    </div>
+           
+    <h3>Animation Mixer</h3>
+        
+    <div class="desc">
+        
+        The stored data form only the basis for the animations - actual playback is controlled by 
+        the [page:AnimationMixer]. You can imagine this not only as a player for animations, but 
+        as a simulation of a hardware like a real mixer console, which can control several animations 
+        simultaneously, blending and merging them.
+
+    </div>
+           
+    <h3>Animation Actions</h3>
+        
+    <div class="desc">
+              
+        The *AnimationMixer* itself has only very few (general) properties and methods, because it 
+        can be controlled by the [page:AnimationAction AnimationActions]. By configuring an 
+        *AnimationAction* you can determine when a certain *AnimationClip* shall be played, paused 
+        or stopped on one of the mixers, if and how often the clip has to be repeated, whether it 
+        shall be performed with a fade or a time scaling, and some additional things, such crossfading 
+        or synchronizing.
+
+    </div>          
+           
+    <h3>Animation Object Groups</h3>
+        
+    <div class="desc">
+              
+        If you want a group of objects to receive a shared animation state, you can use an
+        [page:AnimationObjectGroup].  
+
+    </div>          
+            
+    <h3>Supported Formats and Loaders</h3>
+        
+    <div class="desc">
+		Note that not all model formats include animation (OBJ notably does not), and that only some
+		three.js loaders support [page:AnimationClip AnimationClip] sequences. Several that <i>do</i>
+		support this animation type:
+    </div>
+
+		<ul>
+			<li>[page:JSONLoader THREE.JSONLoader]</li>
+			<li>[page:ObjectLoader THREE.ObjectLoader]</li>
+			<li>THREE.BVHLoader</li>
+			<li>THREE.FBXLoader</li>
+			<li>THREE.FBXLoader2</li>
+			<li>[page:GLTFLoader THREE.GLTFLoader]</li>
+			<li>THREE.MMDLoader</li>
+			<li>THREE.SEA3DLoader</li>
+		</ul>
+   
+    <div class="desc">
+		Note that 3ds max and Maya currently can't export multiple animations (meaning animations which are not
+        on the same timeline) directly to a single file.
+    </div>
+    
+	<h2>Example</h2>
+
+	<code>
+		var mesh;
+
+		// Create an AnimationMixer, and get the list of AnimationClip instances
+		var mixer = new THREE.AnimationMixer( mesh );
+		var clips = mesh.animations;
+
+		// Update the mixer on each frame
+		function update () {
+			mixer.update( deltaSeconds );
+		}
+
+		// Play a specific animation
+		var clip = THREE.AnimationClip.findByName( clips, 'dance' );
+		var action = mixer.clipAction( clip );
+		action.play();
+
+		// Play all animations
+		clips.forEach( function ( clip ) {
+			mixer.clipAction( clip ).play();
+		} );
+	</code>
+
+  </body>
+</html>

docs/page.css

@@ -110,4 +110,4 @@ strong {
 a.permalink {
 	float: right;
 	margin-left: 5px;
-}
+}