path: root/progs/demo/X11/animation/doc.tex

%  This is obsolete regarding the X system  -- jcp

% -*-latex-*-
% Creator: John Tinmouth
% Creation Date: Thu May 9 1991
\documentstyle[11pt]{article}
\newcommand{\X}[1]{{#1}\index{{#1}}}
\begin{document}

\title{A Functional Animation Package in Haskell}
\author{
        John Tinmouth\\
        Computer Science Senior Project\\
         Yale University\\
         Professor Paul Hudak }
\date{9 May 1991}
\maketitle



\section{Introduction}

  	In his paper "A Functional Animation Starter Kit" [ARYA88], Kevi Arya 
proposes an approach to animation that uses functional languages. As
Arya describes, the cost of computing power is falling. This is making
the use of computer animation much more prevalent. However, languages
such as C make it difficult to program animations. What is needed is
a simpler, faster and more accessible way to program graphics. Functional
languages are a very effective means for this, due to their higher order
functions.
 
	Kevi Arya goes on to provide such a functional animation package in
the language Miranda. Haskell in particular is good functional language for
two reasons. It is a completely functional language, doing even I/O in a 
functional manner. Variables are evaluated in a lazy manner allowing infinite 
lists to be manipulated easily, which suits the infinite frames format
of animation. As it is now possible to complete the implementation of
this package is Haskell, my work has been converting these Miranda programs
to Haskell version 1.0-0, Yale Haskell Group. 


  
\section{How to Use the Graphics:  Overview}

  By using higher order functions, it becomes very easy to do rapid 
prototyping of animations. You can quickly throw out an animation of
simple images manipulated in simple ways. For example, if there was
an image of a car, and you wanted it to move left, you could almost 
just describe it in english, and that would be the animation.
\begin{verbatim}
     movie = apply left car
\end{verbatim}

	After the simple model is done, converting it to a more complex model
is simple. Simply make the image, "car" in this case, more complex, and
then modify the "left" function, and you are done.

	There are three stages in making a movie. First of all, you must
define your basic images. These will tend to be Pics put into lists, either
finite or infinite, to be basic Movies. Second, you decide precisely
what kind of motion you want in animation. These are behaviours. A behaviour
modifies a movie over time, changing each successive frame. This includes
motion, changing size, changing from one image to another and so forth. These 
are applied to your basic Movies. Third, you must combine your basic Movies
into your final Movie. If you want a scene of clouds and a man walking, you
must overlay your basic Movie of clouds with your Movie of a walking man.

\section {Original Images or Pics}

	A Movie is a list of frames called Pics. Each of these Pics is a list 
of colored polygons. The Pic is a Color followed by a list of Vectors, 
representing the vertices of the Polygon. The original Pic usually must
be entered by hand, although simple generation routines for boxes, 
triangles and circles are available. You need to produce some of these
basic images in one way or another, so that you have something to 
manipulate.

	To make a Movie, you need a list of these Pics. With a single Pic, you
can generate a sequence of that Pic. With several Pics, you can oscillate
through the Pics in an inifinite list. To generate an infinite list of
Pics of p1, define a Movie, m1 = i p1. 
  The following datatypes are used in this package:

\begin{verbatim}
type Vec	= (Int,Int)
type Color	= Int
type Poly	= (Color,[Vec])
type Pic 	= [Poly]
type Movie	= [Pic]
type Behaviour	= [Pic -> Pic]
\end{verbatim}


\subsection {Modifying Pics}

  Starting with a single Pic, it is possible to create a short list of
Pics to oscillate on. You can flip it, scale it, or otherwise modify the
original Pic (p1) in some way to create another Pic (p2). You can either
keep doing this and produce N images for a Movie of [p1,p2,...,pN], or use
the interpolation functions available to shift from p1 to p2 in N frames,
resulting in a Movie [p1,interp1,interp2,...,interpN-2,p2].
  The list of specific Pic-to-Pic functions is included in the next section,
along with short explanations of what they do.

\subsection {Pic-to-Pic Functions Available}

\begin{verbatim}
overlay_Pic     Args: Pic Pic 
                This takes 2 Pics and just puts them together into one Pic.
                module: R_Picture

put_Pic	        Args: Vec Pic Pic
                This overlays the two Pics, putting Pic-1's center the Vec 
                distance away from Pic-2's center.
                module: R_Picture

over_Pic        Args: Pic Pic
                This puts two images on top of one another, explicitly 
                centering the first on top of the second and forms one Pic.
                module: R_Picture
                
above_Pic       Args: Pic Pic
                This puts the first Pic above the second Pic, at a distance
                of half the combined heights of the Pics and overlays them
                to form one Pic.
                module: R_Picture

beside_Pic      Args: Pic Pic
                This puts the first Pic to the right of the second Pic, at
                a distance of half the combined widths of the Pics and 
                overlays them to form one Pic.
                module: R_Picture

beside2_Pic     Args: Pic Pic
                Withouth analysing the widths of the Pics, it puts the
                first Pic the width of the second Pic to the right and
                overlays them to form one Pic.
                module: R_Picture

scale_Pic       Args: Int Pic 
                This scales the picture in elevenths around its own origin
                and returns that Pic. So if the Int is 22, the Pic will
                scaled by a factor of 2 (22/11).
                module: R_Picture

scale_rel_Pic   Args: Vev Int Pic
                This is another scaling function, but it scales the image
                from the Vec, treating it as the origin. 
                module: R_Picture

mov_Pic         Args: Vec Pic
                This moves the Pic by the amount of the vector.  
                module: R_Picture

movto_Pic       Args: Vec Pic
                This moves the Pic's center to the Vec.
                module: R_Picture

to_orig         Args: Pic
                This moves the Pic's center to the lower,left side of
                the Pic. 
                module: R_Picture

rot_Pic         Args: Vec Float Pic
                This rotates the Pic by the Float in radians, using the Vec
                as the origin of rotation.
                module: R_Picture

twist_Pic       Args: Float Pic
                This rotates the Pic by the Float amount of radians around
                its own center. 
                module: R_Picture

rot_Pic'        Args: Vec Pic
                This rotates the Pic by a certain amount (set in R_Constants)
                using the Vec as the center of rotation. The set amount of
                rotation makes it faster than rot_Pic.
                module: R_Picture

twist_Pic'      Args: Pic
                This rotates the Pic by a certain amoutn (set in R_Constants)
                around the Pic's origin. The set amount of rotation makes
                it faster than twist_Pic.
                module: R_Picture

flipx_Pic       Args: Int Pic
                This flips the Pic around the line x=Int, essentially giving
                a mirror image of the Pic, reversing right and left.
                module: R_Picture


flipy_Pic       Args: Int Pic
                This flips the Pic around the line y=Int, mirror-imaging the
                Pic, reversing up and down.
                module: R_Picture

flip_Pic        Args: Pic
                This flips the Pic around its own x-origin, reversing
                left and right. 
                module: R_Picture

flock_Pic       Args: Int Pic
                This takes the image Pic and copies it out Int*Int times in
                a Int by Int grid pattern, and returns that as an Pic.
                module: R_Picture

set_Color       Args: Int Pic
                This takes an Int standing for a color, and changes the
                color of the Pic to that.
                module: R_Picture 
\end{verbatim}

\subsection{Other Functions for Manipulating Pics}

\begin{verbatim}
i               Args: Any		
                This will take anything and return an infinite stream of them.
                module: R_Utility

osc             Args: [Any]
                This will take a Movie, which is a list of Pics and 
                oscillate them. 
                    [p1]           will give [p1,p1,p1,p1....]
                    [p1,p2,p3,p4]  will give [p1,p2,p3,p4,p3,p2,p1,p2...]
                module: R_Utility
\end{verbatim}

\section{Behaviours and their Application to Movies}

	A Behaviour is a list of functions that will convert one Pic to
another Pic. This list then can be applied to any Movie with one
of the application functions (most often apply). The beauty of the Behaviour
is that once you have a behaviour for moving left, you can move any
Movie left without rewriting the routine every time.
  
	There are specific functions that take a Behaviour and a Movie and
return a new Movie. These are apply and while. If you had a Movie of a
man walking in place, and a Behaviour called left that moves Pics ever
increasing distances left, then you could create a man walking left by:
\begin{verbatim}
        apply left man
\end{verbatim}

	If you want to apply more than one Behaviour to a Movie, you must first
decide whether to do that in sequence or in parallel, and use bSeq and bPar
to reduce the list of Behaviours to a single Behaviour, and then apply
that to a movie. For example:
\begin{verbatim}
        apply (bPar left up) gull
\end{verbatim}
will take a Movie of a gull and move the Pics up and left.

	Most of the basic Behaviours are defined in R\_Behaviour. 

    
\subsection{Defining Customized Packages of Behaviours}

	Often you will have more specialized, or just simpler Behaviours you
want to use. Using the Behaviours and Pic-to-Pic functions, it is very
easy to create your own small library of Behaviours. R\_Defaults is a
module of such Behaviours. For example, to create a Behaviour to move
a Movie right, you  would create a list of mov\_Pic's, each taking a
everincreasingly large x-coordinate.
\begin{verbatim}
        right = [ mov_Pic (x,y) | (x,y) <- zip [0,10,..] [0,..] ] 
\end{verbatim}

	Or if you wanted a behavour to place a Movie at (100,100) twice as
large as before, you could create a new Behaviour from old ones as:
    scaleat= bPar [movto (i (100,100)), scale (i 22)]

\subsection{Behaviours Available}
\begin{verbatim}
flip            Args: none
                This will flip every Pic around its x-origin, resulting in
                mirror images reversing left and right.
                module: R_Behaviour
 		
twist'          Args: none
                This will rotate each Pic by the amount rotunit (see 
                R_Constants) around its origin.
                module: R_Behaviour

mov             Args: [Vec]
                This will move each Pic by its corresponding vector.
                module: R_Behaviour

movto           Args: [Vec]
                This will move each Pic's origin to its corresponding vector.
                module: R_Behaviour

circ_mov        Args: Float Float
                This will move each Pic in a circle, of radius of the first
                Float and by an increment of the second Float, using (0,0)
                as the origin of rotation.
                module: R_Behaviour

scale           Args: [Int]
                Scales every Pic on its origin by the the corresponding Int
                in the list. These Ints represents elevenths, so that a 
                [2,2,...] will scale every Pic by 2/11 .
                module: R_Behaviour

scale_rel       Args: Vec [Int]	
                Same as scale, except that the Pics are all scaled using the
                Vec as the point of origin.
                module: R_Behaviour

twist           Args: [Float]
                This will rotate every Pic by its corresponding Float from
                the list in radians.
                module: R_Behaviour

set_color       Args: [Int]
                This sets each Pic to the color indicated by its 
                corresponding int in the list.
                module: R_Behaviour
	
rot             Args: [Vec] [Float]
                This will rotate each Pic around its corresponding Vec by
                its corresponding Float in radians.
                module: R_Behaviour

big             Args: none
                Scales every Pic up by scaleunit
                module: R_Defaults

huge            Args: none
                This scales every Pic up by 2*scaleunit
                module: R_Defaults

small           Args: none
                This scales every Pic down by 10/11
                module: R_Defaults

tiny            Args: none
                This scale every Pic down by 5/11
                module: R_Defaults

bigger          Args: none
                This scales every Pic in the list by scaleunit more 
                than the previous Pic, so that the n-th element is
                scaled up by (n-1)*scaleunit 
                module: R_Defaults

smaller         Args: none
                This scales every Pic down, so that the n-th element
		is scaled down by (n-1)*(10/11)
                module: R_Defaults

ccw             Args: none
                This rotates every Pic by one rotunit more than the
                previous Pic, in a counterclockwise fashion.
                module: R_Defaults

cw              Args: none
                This rotates every Pic by one rotunit more than the
                previous Pic, in a clockwise fashion.
                module: R_Defaults

up              Args: none
                This moves every Pic up by one unit more than the 
                Previous Pic, so that the n-th element is moved up 
                (n-1) units.
                module: R_Defaults

down            Args: none
                This is same as up, but the Pics move down.
                module: R_Defaults

right           Args: none
                This is same as up, but the Pics move right.
                module: R_Defaults

left            Args: none
                This is same as up, but the Pics move left.
                module: R_Defaults
\end{verbatim}

\subsection{Functions For Behaviours}

\begin{verbatim}
do              Args: Int Behaviour
                This takes the first Int elements of the Behaviour and
                return that.
                module: R_Behaviour

rpt             Args: Int Behaviour
                This takes an Int and returns a Behaviour of length Int.
                However, the n-th Pic-to-Pic in the Behaviour returned
                is made up of the first through (n-1)the Pic-to-Pics of
                the input list.
                module: R_Behaviour

forever         Args: Behaviour
                This makes a finite Behaviour list an infinite one by
                appending the list to itself endlessly.
                module: R_Behaviour

apply           Args: Behaviour Movie
                This takes a Behaviour and applies it to a Movie
                module: R_Behaviour

while           Args: (Boolean function) Behaviour Movie
                As long as the Boolean function evaluates true, this 
                takes a Behaviour and applies it to a Movie. When it
                evaluates to false, no more Pics are produced and
                the Movie is cut short there.
                module: R_Behaviour

bseq            Args: Behaviour Behaviour
                This takes two Behaviour and creates one Behaviour made
                up of the two inputs applies in sequence.
                module: R_Behaviour

bSeq            Args: [Behaviour] Behaviour
                This takes two Behaviour and creates one Behaviour made
                up of the two inputs applies in sequence.
                module: R_Behaviour

bpar            Args: Behaviour Behaviour
                This takes two Behaviour and creates one Behaviour made
                up of the two inputs applies in parallel.
                module: R_Behaviour

bPar            Args: [Behaviour] Behaviour
                This takes two Behaviour and creates one Behaviour made
                up of the two inputs applies in parallel.
                module: R_Behaviour
\end{verbatim}

\section{Creating the Final Movie}

	Finally, you have your basic Movies made up of Pictures and Behaviours.
Now you need to combine them into one Movie. The functions that do this
are found in the module R\_Movie. These functions will take a list of
Movies and return a single Movie combining all the Movies in the list.
How they are combined can be controlled to some extent. Usually they are
just overlayed, but they can be put beside one another, or on top of
one another, or put a Vec distance apart.

	It is also possible to use a combination of these forms. If you wanted
to overaly M1 and M2, and then put that beside M3, you would do:
\begin{verbatim}
        rBESIDE [M3, rOVERLAY [M1,M2] ]
\end{verbatim}
This is acceptable as rOVERLAY will return a single Movie. 

\subsection{Movie Combining Functions}

\begin{verbatim}
rABOVE          Args: [Movie]
                Puts all the Movies into one movie, all above one another.
                module: R_Movie

rBESIDE         Args: [Movie]
                Puts all the Movies into one movie, all beside one another.
                module: R_Movie

rBESIDE2        Args: [Movie]
                Using their absolute coordinates, puts all the Movies
                beside one another.
                module: R_Movie

rOVER           Args: [Movie]
                This lays the Movies on top of one another, centering 
                each Pic so that they share the same origin.
                module: R_Movie

rOVERLAY        Args: [Movie]
                This lays the Movies on top of one another, centering
                each Pic so that they share the smae origin.
                module: R_Movie

pUT             Args: [Vec] Movie Movie
                This takes a list of Vec, and puts each Pic of the
                first Movie in the location of the corresponding
                Vec on top of the Pic of the second Movie and
                returns that list as the new Movie.
                module: R_Movie

\end{verbatim}

\section{Displaying Your Movie}

	Once you have your function for the Movie defined, you need to output
it in some way. Currently, this is done by outputting characters to a file and
running a C Program in X-Windows that displays the contents of the file
as a graphic in the X system. First of all, you must convert the
Movie variable to a stream of characters. This is done by running 
"showm" on the Movie. Be carefull you don't try to convert an infinite list
into characters as the compiler will take awhile to do this. Instead, take
a certain number of frames and convert them with "showm".
\begin{verbatim}
        man\_vm = rOVERLAY [man,vm]
        man\_vmstring = showm (take 20 man&vm)
\end{verbatim}
  Now that you have this string, you need to write it to disk. The 
"writetofile" function does this. It takes a characater string(ie [Char] )
as an argument, and then prompts you for a filename. It then writes the
string to the filename. So to put man\_vm string into a file:
\begin{verbatim}
        main = writetofile man_vmstring
\end{verbatim}
and run the program, where you will prompted for the filename. Or you could:
\begin{verbatim}
        main = writetofile (showm (take 20 man_vm))
\end{verbatim}
to make it more compact.


\subsection{Miscellaneous Usefull Functions}

\begin{verbatim}
inbetween       Args: Int Pic Pic
                This takes an Int and two Pics and returns a Movie 
                with Int Pics interpolating between the two Pics.
                module: R_Inbetween

tween           Args: Int Movie Movie
                This takes an Int and two Movies and returns one
                Movie made up of the first Movie, Int number of
                frames of Pics interpolating between the last
                Pic of the first Movie and the first Pic of the
                second Movie, followed by the second Movie
                module: R_Inbetween

box             Args: Int Int Int
                This takes 3 Ints, the color, width and height of 
                the box and returns a Pic of a box
                module: R_Shapes

tri             Args: Int Vec Vec Vec
                This takes a color and three vectors and returns a
                Pic of a triangle of that colour with those vertices.
                module: R_Shapes

circ            Args: Int Int Int
                This takes a color, the radius and the number of points
                around the circle, and returns a circle with origin at
                (0,0).
                module: R_Shapes
\end{verbatim}

\pagebreak
\large {\bf Appendix:  C Programs to Display on X-Windows}
\\
\\
	The program currently used to run these graphics is called "xcshow".
This takes one argument, the name of the file to be run. When run
in X-Windows, it will produce a window with the first Pic. To run it, click
on the left mouse button inside the window. Clicking again will freeze it.
This will keep cycling through the file, replaying again when it hits the
end of the file, until the window is killed.

	There is also "xshow" which is used to run the monochrome Movies, as
"xcshow" is used to run the color Movies. As this animation package
only produces color Movies, it isn't too usefull.


\pagebreak
\large {\bf References}
\\
\\
\begin{verbatim}
[ARYA88] "The Formal Analysis of a Functiona Animation System", Kevi Arya,
          DPhil,Thesis,Oxford University, Programming Research Group,
          April 1988

[ARYA89] "Processes In A Functional Animation System", Kevi Arya,IBM
          T.J. Research Center, 1989 

[HASK90] "Report On The Programming Language Haskell, Version 1.0",
          YALEU/DCS/RR-777,Yale University,1990
\end{verbatim}

\end{document}