Add documentation about animations

Collect general information about animations in one easy to find place.
New content added and also some content moved from timeline palette documentation.

Task-number: QT3DS-2620
Change-Id: Id58b5b9cea0d59081e006357753c23f5a2db02a3
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

5 files changed, 163 insertions, 83 deletions

diff --git a/doc/src/03-studio/0-menu.qdoc b/doc/src/03-studio/0-menu.qdoc
index a777ddfb..d949f52f 100644
--- a/doc/src/03-studio/0-menu.qdoc
+++ b/doc/src/03-studio/0-menu.qdoc
@@ -106,7 +106,7 @@
     \li
       \uicontrol{Default Interpolation} - Controls whether new animation
       keyframes are created with
-      \l{studio-timeline-palette.html#interpolation}{linear or smooth interpolation}.
+      \l{animations.html#interpolation}{linear or smooth interpolation}.
     \li
       \uicontrol{Timeline Snapping Grid} - When using snapping in the
       timeline, controls which ticks to snap to.
@@ -236,7 +236,7 @@
   press the \c{Delete} key after selecting the keyframes to delete them.
 \li
   \uicontrol{Set Interpolation} - Changes the in and out
-  \l{studio-timeline-palette.html#interpolation}{interpolation}
+  \l{animations.html#interpolation}{interpolation}
   setting for the selected keyframes. This command is
   also available from the context menu when right-clicking in the
   animation portion of the \e{timeline palette}.
diff --git a/doc/src/03-studio/5-timeline-palette.qdoc b/doc/src/03-studio/5-timeline-palette.qdoc
index 2f1a4803..f385ebbd 100644
--- a/doc/src/03-studio/5-timeline-palette.qdoc
+++ b/doc/src/03-studio/5-timeline-palette.qdoc
@@ -309,86 +309,9 @@ palette. Clicking on these numbers will open the Go To Time palette,
 where you may type in an exact time, down to milliseconds, to set
 the playhead to.
 
-\section2 Adjusting Animation
+\section2 Working with Animations
 
-\image Studio-Timeline-Animation-Keyframes.png
-
-Most good visual effects do not "pop" into place, but provide a visual
-transition, even if brief, to help the user understand what happened.
-This is an example on what you can achieve with animations.
-
-\section3 Creating Keyframes
-
-To animate a property of an element, turn on the
-\l{studio-inspector-palette.html#animating-properties}{animation toggle
-in the Inspector palette}. This will add a new keyframe for that
-property at the current playhead time. If the property is not linked to
-the master slide (as with the position shown in the picture above) the
-animation will only be created on the current slide.
-
-To create a new keyframe, move the playhead to a new time and then
-do one of the following:
-
-\list
-\li
-  Ensure that \l{studio-toolbar.html#keyframing}{Autoset Keyframes} is
-  turned on (via the Toolbar, Timeline menu, or by pressing \c{K}),
-  and then change the value of the property (via the Inspector palette
-  or dragging the transform of the element), or
-\li
-  Change the value of the property and then invoke the
-  \l{studio-menu.html#timeline}{Set Changed Keyframes} command (from the
-  Timeline menu, or the keyboard shortcut \c{Ctrl + Shift + K}).
-\endlist
-
-This will create a new keyframe at the current time. You can drag the
-keyframe in the Timeline palette to adjust its time, or double-click it
-to show the Set Keyframe Time dialog where you can enter an exact timing
-value.
-
-Keyframes displayed in green are "dynamic keyframes". For more
-information, see the page
-\e{\l{best-practices-dynamic-keyframes.html}{Dynamic Keyframes}}.
-
-\section3 Copying Keyframes
-
-To copy keyframes from one element to another, follow the steps below.
-
-\list 1
-\li
-  Select the keyframe(s) to copy on an element.
-\li
-  Right-click on one of the selected keyframes and choose \uicontrol {Copy Selected Keyframes}.
-\li
-  Position the playhead at the time where the first keyframe should be
-  placed.
-\li
-  Right click on the time bar for the element and choose \uicontrol{Paste Keyframes}.
-\endlist
-
-\section3 Interpolation
-
-\image Studio-Timeline-Interpolation.png
-
-As the playhead moves from one keyframe to the next, the Qt 3D Studio
-Runtime can perform \e {linear interpolation}, \e {smooth
-interpolation}, or a custom blending somewhere in-between. With linear
-interpolation the value changes at the same rate from one value to the
-next. With smooth interpolation the value starts off holding the
-previous keyframe value, 'accelerates' towards the next keyframe value,
-and then 'decelerates' to stop at the new value.
-
-To set the interpolation, first select the keyframe(s) that you want to
-adjust, then right-click on one of the selected keyframes, and from the
-context menu choose \b {Set Interpolation}. The \b {Ease In} setting
-controls how the value behaves as it approaches the keyframe and the
-\b {Ease Out} setting controls how the value behaves when leaving the
-keyframe.
-
-\note If you find that you are constantly setting your keyframes from
-Smooth to Linear, or vice-versa, you may wish to change the
-\b{Default Interpolation} setting for new keyframes in the
-\l{studio-menu.html#edit}{Application Preferences}.
+For more information on how to work with animations, see the \l Animations documentation.
 
 \section2 Adjusting Time Bars
 
@@ -423,7 +346,6 @@ first time to select the scene or active component, set the playhead
 to a particular time, and then press \c{]} to crop the entire
 slide to that duration.
 
-
 \section2 Customizing Time Bars
 
 To help you keep track of your assets, Studio allows you to apply custom
@@ -468,7 +390,8 @@ animations and slide transitions without leaving Studio.
   or causing Studio to switch to an new slide when the end time for the
   current slide is reached.
 \li
-  The \uicontrol{Stop} command stops any playback. \uicontrol{Stop} replaces \uicontrol{Play} when animation is playing.
+  The \uicontrol{Stop} command stops any playback. \uicontrol{Stop} replaces \uicontrol{Play}
+  when animation is playing.
 \li
   The \uicontrol{Fast-forward} command sets the playhead to the timeline end.
 \li
diff --git a/doc/src/animations.qdoc b/doc/src/animations.qdoc
index 33a83075..64eac60d 100644
--- a/doc/src/animations.qdoc
+++ b/doc/src/animations.qdoc
@@ -30,6 +30,163 @@
 \title Animations
 \page animations.html
 
+In Studio, it is easy to create keyframe animations to object and material properties. It is also
+possible to import animations from 3D creation tools such as Maya, 3D Studio Max, or Blender.
+
+A keyframe is a a time marker that stores the value of a property. A keyframe can for example
+define the X position for an element. To create an animation, add another keyframe for the X
+position of the same element but in another position on the timeline. Studio will determine the
+correct X position for all frames between the two keyframes.
+
+You can animate almost any object or material property. Animatable properties have the
+\inlineimage animationIconInactive.png
+icon next to their name in the inspector palette.
+
+\image light-properties.png
+
+\section1 Create Animations
+
+To animate a property, follow the steps below:
+
+\list 1
+  \li
+  Ensure that \l{studio-toolbar.html#keyframing}{autoset keyframes} is toggled on.
+  \li
+  Select the element in the timeline palette, and set the desire starting value for the
+  animated property.
+  \li
+  Move the playhead to the position in the timeline where you want the animation to start.
+  \li
+  Enable animation for the property by clicking the \inlineimage animationIconInactive.png
+  icon next to the property name in the inspector palette.
+  \li
+  Move the playhead to a new position, then change the value for the animated property.
+\endlist
+
+\image Studio-Timeline-Breadcrumb.png
+
+Now that you have two keyframes in the timeline, you can preview the animation by dragging the
+playhead in the timeline palette, or by running the presentation in the Studio or the Viewer.
+
+Moving the playhead to a new position, and then changing the value of a property with animation
+enabled will create a new keyframe.
+
+\section1 Edit Animations
+
+\section2 Insert Keyframes
+
+As mentioned above, changing the value of an animated property will create a new keyframe if there
+isn't already a keyframe in the same position. This requires that \uicontrol {Autoset Keyframes}
+is toggled on.
+
+To manually insert a keyframe, first place the playhead in the position where you want to create the
+keyframe. Next, do one of the following:
+\list
+  \li
+  Right-click the timebar of the animated element, next select \uicontrol {Insert Keyframe}
+  from the context menu.
+  \li
+  Left-click the timebar of the animated element, next press \uicontrol {S}.
+\endlist
+
+Keyframes will be created for all animated properties for the selected element.
+
+\section2 Delete Keyframes
+
+To delete a keyframe, first select it (\uicontrol {Ctrl + left mouse click} to multi select). Next,
+do one of the following:
+\list
+  \li
+  Press \uicontrol {Del}.
+  \li Right-click the keyframe and select \uicontrol{Delete Selected Keyframe} from the
+  context menu.
+\endlist
+
+To delete all keyframes of an element, do one of the following:
+\list
+  \li
+  Right-click the timebar and select \uicontrol {Delete All Channel Keyframes}.
+  \li
+  Left-click the timebar, next press \uicontrol {Ctrl + Alt + K}.
+\endlist
+
+\section2 Move Keyframes
+
+To move a keyframe to a desired position in the timeline, do one of the following:
+\list
+  \li
+  With the left mouse button, drag and drop it.
+  \note Hold \uicontrol {Shift} while dragging to snap to timeline markers.
+  \li
+  Double-click the keyframe and enter the desired timeline position in the dialog window.
+  \li
+  Right-click the keyframe and select \uicontrol {Set Keyframe Time}. Next, enter the desired
+  timeline position in the dialog window.
+\endlist
+
+\section2 Change Property Values
+
+To change a property value for a keyframe, follow the steps below:
+
+\list 1
+  \li
+  Move the playhead to the keyframe, hold \c {Shift} to snap the playhead to the keyframe.
+  \li
+  Select the desired element in the timeline palette.
+  \li
+  In the inspector palette, change the value of the desired animated property.
+\endlist
+
+\section2 Copy Keyframes
+
+To copy keyframes from one element to another, follow the steps below:
+
+\list 1
+  \li
+  Select the keyframe(s) to copy on an element.
+  \li
+  Right-click on one of the selected keyframes and select \uicontrol{Copy Selected Keyframes} from
+  the context menu.
+  \li
+  Position the playhead at the time where the first keyframe should be placed.
+  \li
+  Right click on the time bar for the element and select \uicontrol {Paste Keyframes} from.
+  the context menu.
+\endlist
+
+\section2 Interpolation
+
+As the playhead moves from one keyframe to the next, the Qt 3D Studio
+Runtime can perform \e {linear interpolation}, \e {smooth
+interpolation}, or a custom blending somewhere in-between. With linear
+interpolation the value changes at the same rate from one value to the
+next. With smooth interpolation the value starts off holding the
+previous keyframe value, accelerates towards the next keyframe value,
+and then decelerates to stop at the new value.
+
+To set the interpolation, first select the keyframe(s) that you want to
+adjust, then right-click one of the selected keyframes, and from the
+context menu choose \uicontrol {Set Interpolation}. The \uicontrol {Ease In} setting
+controls how the value behaves as it approaches the keyframe and the
+\uicontrol {Ease Out} setting controls how the value behaves when leaving the
+keyframe.
+
+\image Studio-Timeline-Interpolation.png
+
+\note If you find that you are constantly setting your keyframes from
+Smooth to Linear, or vice-versa, you may wish to change the
+\uicontrol{Default Interpolation} setting for new keyframes in the
+\l{studio-menu.html#edit}{Application Preferences}.
+
+\section1 Import Animations
+
+You can import transform (scale/rotation/location) animations from 3D creation tools
+such as Maya, Blender, 3D Studio Max and Modo.
+
+Read more in the \l {Working with 3D Content} section.
+
+\section1 Further Topics
+
 \list
   \li
   \l{Studio: Timeline Palette}{The Timeline}
diff --git a/doc/src/images/Studio-Timeline-Interpolation.png b/doc/src/images/Studio-Timeline-Interpolation.png
index 6754f1f3..f8b84487 100644
--- a/doc/src/images/Studio-Timeline-Interpolation.png
+++ b/doc/src/images/Studio-Timeline-Interpolation.png
diff --git a/doc/src/images/light-properties.png b/doc/src/images/light-properties.png
new file mode 100644
index 00000000..a5f5528a
--- /dev/null
+++ b/doc/src/images/light-properties.png