Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 343b.lha / OrbitX / read.me < prev next >

Wrap

Text File | 1990-01-20 | 23.1 KB | 655 lines

How to use "orbitX" * orbitX.doc * --**********-- OrbitX is a program that lets you explore the behavior of orbiting objects. It can be used simply to watch the delicate motion of the objects, or to generate drawings which can be saved for use with other Amiga programs. This document will explain some of the theory behind what is going on when you run orbitX, as well as serve as a general guide to using the program. * installation * --************-- To use orbitX you will need an Amiga (1000, 500, 2000, 2500) with 512k of ram or more, Workbench 1.2 or 1.3 (with the appropriate Kickstart rom or disk), and version 1.3 of the ARP library. If you don't have the ARP library (or if you have only an earlier version of it) you should be able to find a copy on CompuServe's AmigaTech forum, or a similar forum on another network, or ask your local Amiga users' group or any other such distributor of public-domain software. Before you do anything else you will need to use "zoo" to de-arc the program and all its support files. I recommend putting all the files on a newly-formatted blank floppy disk. The files will all need to be in the same drawer if you are putting orbitX on your hard disk. Consult the documentation you have for "zoo" for more information on how to remove files from an archive. If you want to run orbitX from a RAM or RAD disk you will need to copy all its support files as well as the executable. I have included a script file that will copy orbitX to a RAM disk, but if you have a 'floppy-sized' RAD disk you will probably find it faster and easier to do a disk copy. I definitely recommend copying orbitX to RAM or RAD to speed up loading time. * distribution * --************-- You can make as many copies of orbitX as you want, and give them to whomever you choose, by any means you have available to you, but please keep all the files together (including all the documentation), and don't sell or otherwise make money from the distribution of this program. I am also asking that you complete the questionnaire included with this program (it's call "write.me"), and send your responses back to me on CompuServe. My name and user ID can be found at the end of this file. It should only take a few minutes of your time, and I really do need the responses. In addition to this I am also interested in the kinds of Page 1 How to use "orbitX" images you have created with orbitX, so, if you've come up with something you really like, save it as a "status file" and send it to me on CompuServe (status files are quite small, and should transfer very quickly). * use * --***-- To start the program simply double-click on the orbitX icon or type "run orbitX" in your CLI or shell. The screen will go black (except for your mouse pointer), and the program will load. Don't do anything else until you see a gray "x" in the middle of the screen and an orange ball orbiting it (leaving a gray trail). If you press the right mouse button you will see three menus (called "system", "balls", and "all") whose selections are all pictures, which I will now explain. * menu diagram * --************-- system balls all ------ ----- --- about largest on/off "x" . radius on/off . direction position . center clear screen smallest position background color on/off trail color add ball radius trail on/off disk direction save picture center load status position save status trail color quit trail on/off Page 2 How to use "orbitX" * the menus * --*********-- The "system" menu: This contains menu items that affect the whole of orbitX. The selections are as follow: 1. about orbitX When you select this a window with an explanation of some of the basic principles behind orbitX will appear on the orbitX screen. When you are done reading click on the "closebox" at the upper left corner of the box to resume normal orbitX operations. (If you are running orbitX on a system with 512k you will not be able to 'drag' this window.) 2. "x" This menu item contains a sub-menu for operations that will affect the "x" or center marker in orbitX. It has the following options available: a. on/off This will turn the image of the "x" on or off. The check mark to the left of the "x" will reflect the status of the "x" (if the check is on the "x" is on). b. position When you select this your mouse pointer will take on the image of the "x", and you will be able to reposition the "x" anywhere an the screen. When you've moved the "x" to where you would like it to stay, push the left mouse button and the "x" will be at this new position. Do not try to use the menus again until your mouse pointer is back to normal (they won't do anything). 3. clear the screen This will erase any paths that may currently be on the screen. It will not affect weather or not paths will continue to be drawn. 4. background color When you select this a requester will appear on the screen with three slider gadgets and the words "cancel" and "update" on it. The top slider controls the amount of red in the background color, the middle slider the amount of green, and the bottom slider the amount of blue. You can either click (with the left mouse button) on the small rectangle and move the mouse left and right while holding down the button, or you can click the left mouse button on the space around the small rectangle and it will move in that direction. The color of the background will change as you move these sliders. Once you have adjusted the color to what you want, you can click (the left mouse button) on the word "update" and the color will stay as what you have set it to. If you click on the word "cancel" the background color will go back to what it was before you changed it. 5. add a ball Page 3 How to use "orbitX" When you select this another ball will be added into the system. It will be slightly smaller than the smallest ball currently in the system, and will appear to the right and below the previously smallest ball. It will start out orbiting this ball and leaving a trail. If you already have six balls in the system, you will not be able to select this (it will be "ghosted", and will not highlight when you move the mouse over it). The new ball will have its own menu item and sub-menu on the "balls" menu. 6. disk operations This menu item contains a sub-menu that lets you access the disk (any disk on your Amiga) to load and save status files, or to save the screen as an IFF picture. The selections are: a. save a picture Select this and you will be able to save an IFF picture of the screen. This picture can be loaded into almost any paint program available for the Amiga. It will be a hi-res, interlaced, 16-color picture. If you select the name of a picture that already exists, it will be replaced with this new picture. b. load status This will load a status file from disk. A status file is a file that contains all the information that controls the position, motion, and appearance of all the balls and the environment of orbitX. It is a fast and convenient way of saving and restoring (regenerating) pictures you may find interesting. I have included a few status files as examples of what can be done in orbitX. I named my status files with a ".orb" at the end of the name for easy identification, but you can name your status files anything you choose (so long as there isn't something else by that name already). Status files are ordinary ASCII files that can be read in any text editor (such as Notepad or Emacs) and are explained in another part or this document. c. save status This selection allows you to save the current status of orbitX so that it can be examined or restored at another time. Read the "load status" explanation for more about this. 7. quit the program This will end your orbitX session and let you use your Amiga for other things. The "balls" menu: This contains an item for each ball in the system, and a sub-menu for each item. The selections on all the sub-menus are the same, and perform the same operation for a different ball. Each time you add a ball to the system (with "add ball" on the "system" menu) a new item with its own sub-menu will be added to this menu. The sub-menu selections are: 1. on/off This will turn the image of the ball on or off (depending on its current status). The checkmark to the left of the ball will Page 4 How to use "orbitX" tell you weather or not this ball's image is currently on. Pay attention to this checkmark, it may be the only way to tell if a ball is on or off if it has wandered off the screen. 2. set the radius When you select this a requester will appear that will allow you to change the radius of this ball. The slider is set to reflect the current distance of the ball from its center, so if you move it to the left the ball will move closer to its center, and to the right it will move further away. Click on the word "update" to use the new value you have set, or "cancel" to leave the radius unchanged. These changes do not happen immediately. After you have changed the radius, the ball will gradually spiral into its new orbit. If the ball was in the process of spiraling into a new orbit when you selected this, the initial slider setting reflects the current distance, and NOT the radius that the ball is trying to spiral into. 3. change direction If the ball is going clockwise this will make it go counterclockwise. If it is going counterclockwise this will make it go clockwise. 4. set center This lets you specify what you want this ball to orbit around. A requester will appear with pictures of all the current balls, the "x", and the words "closest" and "cancel" on it. If you want the ball to orbit the "x" or one of the other balls just click on the picture of what you want the ball to orbit. Note that a ball cannot orbit itself, and the picture of the ball whose center you are selecting will appear right next to the words "set center" on the requester. If you click on the word "closest" the ball will switch around, orbiting whatever it is closest to at any given moment, providing that the object is bigger than it is (in this instance the "x" is the biggest thing in orbitX). If you select "closest" for the first ball it will orbit only the "x" (because it's bigger than all the other balls); if you select this for the second ball it will switch back and forth between orbiting the "x" and orbiting the first ball. 5. position This lets you place the ball anywhere on the screen. It works just like positioning the "x". If balls wander off the screen you can use this to reposition them back onto the screen. 6. trail color This will let you change the color of the trail that this ball is leaving behind it. The requester is the same as the one that changes the background color. Note that you can change the trail color even if this ball is not currently leaving a trail. The words "set color" will be written in the same color as that of the trail. 7. trail on/off This will turn on and off the trailing of this ball. It will Page 5 How to use "orbitX" not remove trails that have been drawn already. If the checkmark is on this ball is currently leaving a trail. The "all" menu: This menu has the same items on it as the sub-menus in the "balls" menu. The operations performed by this menu are the same as for the sub-menus, except that on this menu the operations will be performed for all the balls at the same time. This is a convenient way of changing all the trails to the same color, or giving all the balls the same radius for example. Note that the "direction", "on/off" and "trail on/off" selections will change the current status of the direction, imagery and trails for all the balls based on what they are when you select it, rather than turn them all on and off if they do not already have the same status as one another. Page 6 How to use "orbitX" * status files * --************-- Status files are files which contain all the information about the positions, motion, and appearance of all the balls in the system. They are the primary means of saving and restoring the status of orbitX. I have made these files "human-readable" mainly to satisfy the users' curiosity about the types of information that create various images. I would strongly recommend not editing these files unless you really know what you are doing. Comments and extra lines or spaces are not permitted in these files. Any error in one of these files could cause orbitX to crash when you try to load the file. The file contains the following information. line # 1: file description code (the same for all status files) line # 2: file name line # 3: the number of balls line # 4: horizontal position of "x" line # 5: vertical position of "x" line # 6: 0 if "x" is off; -1 if "x" is on line # 7: -1 if any of the balls are orbiting "x"; 0 otherwise line # 8: background color line # 9: "the orbitals:" line #10: number of this ball ("Orbital # 1") line #11: horizontal position of ball line #12: vertical position of ball line #13: ball's horizontal center line #14: ball's vertical center line #15: number of the ball that this ball is orbiting line #16: -1 if this ball is orbiting proximally; 0 otherwise line #17: this ball's 'target' radius line #18: -1 if this ball is going counter-clockwise; 0 otherwise line #19: ball's quadrant relative to its center (0 - 3) line #20: ball's delta value line #21: if < 1 ball is spiraling out; > 1 ball is spiraling in line #22: ball's current distance from its center line #23: -1 if ball's image is on; 0 if it's off line #24: -1 if ball is leaving a trail; 0 otherwise line #25: trail color ( Lines #10 - #25 are repeated to reflect the status of each ball in the system. ) Page 7 How to use "orbitX" * theory * --******-- There are three basic types of orbits you can model with orbitX: 1. Epicyclic orbits. Set one ball orbiting the "x", and another ball orbiting that ball. When you add balls into orbitX, each ball will automatically orbit the previous ball, displaying this sort of epicyclic behavior. 2. Recursive orbits. Set the first ball orbiting the second ball, and set the second ball orbiting the first ball. You will need to use very small radii for all the balls involved in a recursive set. Note that the position of the "x" does not affect the paths of recursively orbiting sets. 3. Proximal orbits. Set the center of a ball (other than the first ball) to "closest", and it will orbit either the "x" or the closest ball to it that is larger than it is. This would cause the first ball to orbit only the "x", and the second ball to switch back and forth between orbiting the"x" and the first ball. The three types of behavior can also be combined to create more complex behavior. * multi-tasking * --*************-- I would strongly advise you not to multi-task other programs with orbitX. Not only would it slow down other operations to a crawl, but it uses all the hardware sprites and much of the graphics memory as well. I have found that the presence of a low-res (320 pixel wide) screen can cause the last two sprites to scramble in appearance. If you run into this problem, shut down any application that uses a low-res screen, and the sprites should return to their normal appearance. I would also recommend not depth-arranging the orbitX screen. There are no depth-arranging gadgets on the screen for this reason (the "Amiga-M" and "Amiga-N" are still active if you should choose not to heed this advice). Page 8 How to use "orbitX" * the program * --***********-- OrbitX was written entirely in JForth version 2.0. Source code is available upon request and requires this version of the language. It makes extensive use of JForth's object-oriented development environment (ODE), and also uses many of the language's other unique features. JForth is published by: Delta Research P.O. Box 1051 San Rafael, CA 94915 Interestingly enough for those of you knowledgable about mathematics and programming, orbitX is written entirely in fixed-point mathematics. No sines or cosines are used in determining the trajectories of the balls. This was done by using Bresenham's circle-drawing algorithm, which is easily adapted to calculating not only circular paths, but paths that spiral in or out as well. Most of my familiarity with this algorithm comes from: "Procedural Elements for Computer Graphics" David F. Rogers McGraw-Hill Book Company 1985 and "Principles of Interactive Computer Graphics" William M. Newman and Robert F. Sproull McGraw-Hill Book Company 1979 * about me * --********-- I consider myself first and foremost to be an artist. I program because it is a good way to have total control over what a computer will do. I use computers because I find it a good way to create work that is interactive, and can directly involve the viewer/user in the work. I've been programming small computers as a student since 1982, and I find them an interesting platform for distributing art to the general public. I use the Amiga because it has perhaps the best graphics of any small, widely available computer on the market today. To write to me on CompuServe: Harriet Lurie ID#: 73760,3624 Page 9 Page 10