From dd8cf4614b6734cbd83d94a50b076a5e542c3aa4 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Thu, 27 Apr 2017 22:47:46 -0400
Subject: scripting: Add a tweening procedure.

* chickadee/scripting.scm (tween): Reimplement procedure.
* chickadee/math/easings.scm: New file.
* Makefile.am (SOURCES): Add it.
* doc/api.text (Easings, Tweening): New subsections.
---
 doc/api.texi | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

(limited to 'doc')

diff --git a/doc/api.texi b/doc/api.texi
index 1a56039..c3543b8 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -410,6 +410,7 @@ detection.
 * Vectors::                     Euclidean vectors.
 * Matrices::                    Transformation matrices.
 * Rectangles::                  Axis-aligned bounding boxes.
+* Easings::                     Easing functions for interesting animations.
 @end menu
 
 @node Basics
@@ -435,6 +436,60 @@ Half of @var{pi}.
 @node Rectangles
 @subsection Rectangles
 
+@node Easings
+@subsection Easings
+
+@deffn {Scheme Procedure} linear @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} smoothstep @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-quad @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-out-quad @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-out-quad @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-cubic @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-out-cubic @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-out-cubic @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-quart @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-out-quart @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-out-quart @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-quint @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-out-quint @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-out-quint @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-sine @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-out-sine @var{t}
+@end deffn
+
+@deffn {Scheme Procedure} ease-in-out-sine @var{t}
+@end deffn
+
 @node Graphics
 @section Graphics
 
@@ -868,6 +923,7 @@ of scheduling tasks.
 @menu
 * Agendas::                     Scheduling tasks.
 * Coroutines::                  Cooperative multitasking.
+* Tweening::                    Animations.
 * Channels::                    Publish data to listeners.
 @end menu
 
@@ -1069,6 +1125,37 @@ Wait for a message from @var{channel}.
 Evaluate @var{body} in an endless loop.
 @end deffn
 
+@node Tweening
+@subsection Tweening
+
+Tweening is the process of transitioning something from an initial
+state to a final state over a pre-determined period of time.  In other
+words, tweening is a way to create animation.  The @code{tween}
+procedure can be used within any coroutine like so:
+
+@example
+(define x 0)
+(coroutine
+  ;; 0 to 100 in 60 ticks of the agenda.
+  (tween 60 0 100 (lambda (y) (set! x y))))
+@end example
+
+@deffn {Scheme Procedure} tween @var{duration} @var{start} @var{end} @var{proc} [#:step 1 #:ease @code{smoothstep} #:interpolate @code{lerp}]
+Transition a value from @var{start} to @var{end} over @var{duration},
+sending each succesive value to @var{proc}.  @var{step} controls the
+amount of time between each update of the animation.
+
+To control how the animation goes from the initial to final state, an
+``easing'' procedure may be specified.  By default, the
+@code{smoothstep} easing is used, which is a more pleasing default
+than a simplistic linear function.  @xref{Easings} for a complete
+list of available easing procedures.
+
+The @var{interpolate} procedure computes the values in between
+@var{start} and @var{end}.  By default, linear interpolation (``lerp''
+for short) is used.
+@end deffn
+
 @node Channels
 @subsection Channels
 
-- 
cgit v1.2.3