docs: Add visual cue for Animator's key frames

We should explain what a "key frame" is for ClutterAnimator, possibly
with some sort of visual cue.

This allows me to demonstrate my poor skills at using Inkscape, as well
as my overall bad taste for graphics design.

clutter/clutter-animator.c

@@ -37,6 +37,27 @@
  * through the #ClutterScript definition format, but it comes with a
  * convenience C API.
  *
+ * <refsect2 id="ClutterAnimator-key-frames">
+ *   <title>Key Frames</title>
+ *   <para>Every animation handled by a #ClutterAnimator can be
+ *   described in terms of "key frames". For each #GObject property
+ *   there can be multiple key frames, each one defined by the end
+ *   value for the property to be computed starting from the current
+ *   value to a specific point in time, using a given easing
+ *   mode.</para>
+ *   <para>The point in time is defined using a value representing
+ *   the progress in the normalized interval of [ 0, 1 ]. This maps
+ *   the value returned by clutter_timeline_get_duration().</para>
+ *   <figure id="easing-modes">
+ *     <title>Key Frames</title>
+ *     <graphic fileref="animator-key-frames.png" format="PNG"/>
+ *   </figure>
+ *   <para>In the image above the duration of the animation is
+ *   represented by the blue line. Each key frame is the white dot,
+ *   along with its progress. The red line represents the computed
+ *   function of time given the easing mode.</para>
+ * </refsect2>
+ *
  * <refsect2 id="ClutterAnimator-script">
  *   <title>ClutterAnimator description for #ClutterScript</title>
  *   <para>#ClutterAnimator defines a custom "properties" property

doc/reference/clutter/Makefile.am

@@ -106,6 +106,7 @@ EXTRA_HFILES=\
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
 HTML_IMAGES=\
 	actor-box.png \
+	animator-key-frames.png \
 	bin-layout.png \
 	box-layout.png \
         easing-modes.png \
@@ -157,6 +158,8 @@ include $(top_srcdir)/gtk-doc.make
 # e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST += \
 	actor-box.png \
+	animator-key-frames.png \
+	animator-key-frames.svg \
 	bin-layout.png \
 	box-layout.png \
         easing-modes.png \

doc/reference/clutter/animator-key-frames.svg

@@ -0,0 +1,271 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="800px"
+   height="600px"
+   id="svg4624"
+   version="1.1"
+   inkscape:version="0.47 r22583"
+   sodipodi:docname="animator-key-frames.svg">
+  <defs
+     id="defs4626">
+    <marker
+       inkscape:stockid="StopM"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="StopM"
+       style="overflow:visible">
+      <path
+         id="path6098"
+         d="M 0.0,5.65 L 0.0,-5.65"
+         style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt"
+         transform="scale(0.4)" />
+    </marker>
+    <marker
+       inkscape:stockid="DotS"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="DotS"
+       style="overflow:visible">
+      <path
+         id="path5993"
+         d="M -2.5,-1.0 C -2.5,1.7600000 -4.7400000,4.0 -7.5,4.0 C -10.260000,4.0 -12.5,1.7600000 -12.5,-1.0 C -12.5,-3.7600000 -10.260000,-6.0 -7.5,-6.0 C -4.7400000,-6.0 -2.5,-3.7600000 -2.5,-1.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;marker-end:none"
+         transform="scale(0.2) translate(7.4, 1)" />
+    </marker>
+    <marker
+       inkscape:stockid="DotL"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="DotL"
+       style="overflow:visible">
+      <path
+         id="path5987"
+         d="M -2.5,-1.0 C -2.5,1.7600000 -4.7400000,4.0 -7.5,4.0 C -10.260000,4.0 -12.5,1.7600000 -12.5,-1.0 C -12.5,-3.7600000 -10.260000,-6.0 -7.5,-6.0 C -4.7400000,-6.0 -2.5,-3.7600000 -2.5,-1.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;marker-end:none"
+         transform="scale(0.8) translate(7.4, 1)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Lstart"
+       style="overflow:visible">
+      <path
+         id="path5943"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(1.1) translate(1,0)" />
+    </marker>
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 300 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="800 : 300 : 1"
+       inkscape:persp3d-origin="400 : 200 : 1"
+       id="perspective4632" />
+    <inkscape:perspective
+       id="perspective8086"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective8086-4"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective8121"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective8143"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective8198"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <inkscape:perspective
+       id="perspective8198-3"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4142136"
+     inkscape:cx="175.65326"
+     inkscape:cy="447.97925"
+     inkscape:current-layer="layer1"
+     inkscape:document-units="px"
+     showgrid="false"
+     inkscape:object-paths="true"
+     inkscape:object-nodes="true"
+     inkscape:snap-smooth-nodes="false"
+     inkscape:snap-nodes="true"
+     inkscape:window-width="1208"
+     inkscape:window-height="677"
+     inkscape:window-x="238"
+     inkscape:window-y="162"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata4629">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     id="layer1"
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer">
+    <rect
+       style="fill:#808080;fill-rule:evenodd;stroke:#ffffff;stroke-width:0.87221748px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       id="rect5408"
+       width="500.12778"
+       height="262.3963"
+       x="4.9361086"
+       y="4.9361086"
+       ry="10.774727"
+       inkscape:export-filename="/home/ebassi/Source/clutter/clutter/doc/reference/clutter/animator-key-frames.png"
+       inkscape:export-xdpi="90"
+       inkscape:export-ydpi="90" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot8172"
+       style="font-size:36px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans Bold"><flowRegion
+         id="flowRegion8174"><rect
+           id="rect8176"
+           width="41.901608"
+           height="54.149387"
+           x="103.94469"
+           y="50.578033"
+           style="font-size:36px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;font-family:Sans;-inkscape-font-specification:Sans Bold" /></flowRegion><flowPara
+         id="flowPara8180">0.20.</flowPara></flowRoot>    <g
+       id="g2899">
+      <path
+         d="m 114.32613,193.09673 c 0,0 137.26963,-81.90085 137.26963,-81.90085"
+         style="fill:none;stroke:#d40000;stroke-width:3.75110221;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+         id="path8109" />
+      <path
+         d="m 252.12133,110.67031 c 0,0 67.50359,0.8371 67.50359,41.25377 0,40.41667 65,41.25001 65,41.25001"
+         style="fill:none;stroke:#d40000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+         id="path8111" />
+    </g>
+    <g
+       id="g2880">
+      <g
+         transform="translate(2.1213203,21.92031)"
+         id="g8160">
+        <path
+           style="fill:none;stroke:#000080;stroke-width:5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:none"
+           d="M 35.001966,80 469.1647,80"
+           id="path7312" />
+        <path
+           sodipodi:type="arc"
+           style="fill:#f2f2f2;fill-opacity:1;stroke:#000080;stroke-width:5;stroke-linecap:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+           id="path8072"
+           sodipodi:cx="129.16667"
+           sodipodi:cy="80"
+           sodipodi:rx="8.333333"
+           sodipodi:ry="8.333333"
+           d="m 137.5,80 c 0,4.602373 -3.73096,8.333333 -8.33333,8.333333 -4.60237,0 -8.33333,-3.73096 -8.33333,-8.333333 0,-4.602373 3.73096,-8.333333 8.33333,-8.333333 4.60237,0 8.33333,3.73096 8.33333,8.333333 z"
+           transform="translate(-15,0.41666667)" />
+        <path
+           transform="translate(120.83334,0.41666632)"
+           sodipodi:type="arc"
+           style="fill:#f2f2f2;fill-opacity:1;stroke:#000080;stroke-width:5;stroke-linecap:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+           id="path8072-1"
+           sodipodi:cx="129.16667"
+           sodipodi:cy="80"
+           sodipodi:rx="8.333333"
+           sodipodi:ry="8.333333"
+           d="m 137.5,80 c 0,4.602373 -3.73096,8.333333 -8.33333,8.333333 -4.60237,0 -8.33333,-3.73096 -8.33333,-8.333333 0,-4.602373 3.73096,-8.333333 8.33333,-8.333333 4.60237,0 8.33333,3.73096 8.33333,8.333333 z" />
+        <path
+           transform="translate(253.33333,-3.4057873e-6)"
+           sodipodi:type="arc"
+           style="fill:#f2f2f2;fill-opacity:1;stroke:#000080;stroke-width:5;stroke-linecap:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+           id="path8072-2"
+           sodipodi:cx="129.16667"
+           sodipodi:cy="80"
+           sodipodi:rx="8.333333"
+           sodipodi:ry="8.333333"
+           d="m 137.5,80 c 0,4.602373 -3.73096,8.333333 -8.33333,8.333333 -4.60237,0 -8.33333,-3.73096 -8.33333,-8.333333 0,-4.602373 3.73096,-8.333333 8.33333,-8.333333 4.60237,0 8.33333,3.73096 8.33333,8.333333 z" />
+      </g>
+      <flowRoot
+         transform="translate(14.142135,33.234018)"
+         style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#f2f2f2;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+         id="flowRoot8182"
+         xml:space="preserve"><flowRegion
+           id="flowRegion8184"><rect
+             style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#f2f2f2;font-family:Sans;-inkscape-font-specification:Sans"
+             y="27.950617"
+             x="83.438599"
+             height="36.769554"
+             width="59.396969"
+             id="rect8186" /></flowRegion><flowPara
+           id="flowPara8188">0.2</flowPara></flowRoot>      <flowRoot
+         transform="translate(150.31407,32.203619)"
+         style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#f2f2f2;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+         id="flowRoot8182-2"
+         xml:space="preserve"><flowRegion
+           id="flowRegion8184-7"><rect
+             style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#f2f2f2;font-family:Sans;-inkscape-font-specification:Sans"
+             y="27.950617"
+             x="83.438599"
+             height="36.769554"
+             width="59.396969"
+             id="rect8186-3" /></flowRegion><flowPara
+           id="flowPara8236">0.5</flowPara></flowRoot>      <flowRoot
+         transform="translate(282.54304,31.496512)"
+         style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#f2f2f2;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+         id="flowRoot8182-0"
+         xml:space="preserve"><flowRegion
+           id="flowRegion8184-4"><rect
+             style="font-size:24px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#f2f2f2;font-family:Sans;-inkscape-font-specification:Sans"
+             y="27.950617"
+             x="83.438599"
+             height="36.769554"
+             width="59.396969"
+             id="rect8186-4" /></flowRegion><flowPara
+           id="flowPara8238">0.8</flowPara></flowRoot>    </g>
+  </g>
+</svg>