Animated Images, Simulating Worlds

world.ss

The teachpack provides the tools to write simple animations and interactive games. The first and simplest approach is to set up a simulation:

run-simulation : Nat Nat Number [Nat -> Scene] -> true
(run-simulation width height r create-image) creates and shows a width x height canvas, starts a clock, ticking every r (usually fractional) seconds, and, every time the clock ticks, it applies create-image to the number of ticks passed since this function call.

In addition, the function pops up a frame and displays the pictures that create-image generates. The result is a simple animation.

Optional: the function consumes an optional fifth argument, a boolean. If this argument is false or missing, run-simulation acts as described; if it is present and true, the function can create an animated GIF of the simulation after you stop it.

Example:

(define (create-UFO-scene height)
  (place-image UFO 50 height (empty-scene 100 100)))

(define UFO (overlay (circle 10 'solid 'green) (rectangle 40 4 'solid 'green)))

(run-simulation 100 100 (/ 1 28) create-UFO-scene)

For animated worlds and games, using the teachpack requires that you provide a data definition for World. In principle, there are no constraints on this data definition.

The teachpack works with two basic forms of data for visualizing the world:

• Image, which are either inserted into DrScheme via the "Special" menu or constructed from the functions below; and
• Scene, which are created from Images. Specifically, a scene is an image whose pinhole is at position (0,0).

1. big-bang : Nat Nat Number World -> true
(big-bang width height n w) creates and shows a width x height canvas, starts the clock, makes it tick every n seconds, and makes w the first world
2. big-bang : Nat Nat Number World Boolean -> true
big-bang takes an optional fifth argument. If it is true, the world allows the generation of images from the animation, including an animated GIF image
3. on-tick-event : (World -> World) -> true
(on-tick-event tock) means that DrScheme must call tock on the current world every time the clock ticks; it uses the result as the next world
4. on-key-event : (World KeyEvent -> World) -> true
(on-key-event change) means that DrScheme must call change on the current world and a (representation of the) keyevent for every keystroke the programmer (user of the computer) makes; it uses the result as the next world

   
      ;; A KeyEvent is one of: 
      ;; -- Char (char?)
      ;; -- Symbol (symbol?)
   
      When the Keyevent is a char, the programmer (user of the computer) has hit an
      alphanumeric key. Symbols such as 'left, 'right,
      'up, 'down, 'release denote arrow keys
      or the events of releasing a key on the keypad. 
   

5. on-mouse-event : (World Nat Nat MouseEvent -> World) -> true
(on-mouse-event clack) means that DrScheme must call clack on the current world, the current x and y coordinates of the mouse, and and a (representation of the) mouse event for every action of the mouse the programmer (user of the computer) makes; it uses the result as the next world

   
     ;; A MouseEvent is one of:
     ;; - 'button-down
     ;; - 'button-up
     ;; - 'drag
     ;; - 'move
     ;; - 'enter
     ;; - 'leave
   
      The symbols denote the appropriate action with the mouse and (any of)
      its button(s).
   

6. on-redraw : (World -> Scene) -> true
(on-redraw world->scene) means that DrScheme calls world->image whenever the canvas must be redrawn (usually after a tick event/a keyboard event/a mouse event has occurred); the function consumes the current world and produces a scene, which is then displayed in the teachpack's canvas
7. end-of-time : String u Symbol -> World
   When DrScheme evaluates (end-of-time "the end"), it stops the clock and displays the given string or symbol; no further tick events, key events, or redraw events take place until the world is created again.

For the creation of scenes from the world, use the following functions plus the functions on images below:

1. nw:rectangle : Nat Nat Mode Color -> Image
(nw:rectangle width height mode color) creates a width x height rectangle, solid or outlined, with its anchor in the NW corner
2. empty-scene : Nat Nat -> Scene
(empty-scene width height) creates a width x height "scene" (frame with origin in NW)
3. place-image : Image Number Number Scene -> Scene
(place-image image x y scene) places image at (x,y) into scene; (x,y) are comp. graph. coordinates
4. scene+line : Scene Number Number Number Number Color -> Scene
(scene+line scene x0 y0 x1 y1 c) places a line of color c from (x0,y0) to (x1,y1) into scene; (x,y) are comp. graph. coordinates; in contrast to the image.ss add-line function, this one cuts off those portions of the line that go beyond the boundaries of the given Scene.
5. run-movie : (Listof Image) -> true
(run-movie loi) shows the list of images in loi in a time-delayed manner; assume: all images are of the same size

Image Manipulation

Finally, the teachpack provides all the functions that image.ss provides. For completeness, the documentation of this teackpack is included here:
Data definition:

;; Mode is one of the following two symbols or strings: 
;; -- 'solid 
;; -- 'outline 
;; -- "solid"
;; -- "outline"

;; Interpretation: 'solid is used for creating solid basic
;; shapes; 'outline is used for creating outlines of basic
;; shapes. Strings are used in an analogous manner. 

(define-struct color (red green blue))
;; A CS is a structure: (make-color N N N)
;; where N is between 0 and 255 (inclusive).

;; Color is one of:
;; -- a color symbol, e.g., 'blue
;; -- a color string, e.g., "blue"
;; -- a CS, e.g., (make-color 0 0 255), which also denotes blue. 

;; Interpretation: Color arguments are used to paint the shapes
;; or their outlines. See below for more information about color structs.

;; List-of-color is one of:
;; -- empty
;; -- (cons Color List-of-color)