ReadMe for the "What Time Is It?" Project For Apple //e ProDOS 8 Written in Aztec C65 in the AppleX Cross-Development Environment (C) Copyright Bill Buckels 1991-2008 All Rights Reserved. BEFORE USING, YOU MUST READ AND AGREE TO THE DOCUMENT LICENCE.TXT IN ITS ENTIRETY OR REMOVE ALL OF THIS FROM YOUR COMPUTER NOW. DO NOT CHANGE ANY OF THIS UNLESS YOU HAVE A COMPLETE UNDERSTANDING OR IT MAY NOT WORK! Overview This project assumes that you have the AppleX environment installed and that you are working within the Windows XP cmd window that the shortcut that comes with AppleX provides. I am not going to explain this further. If you don't know what I'm talking about install AppleX available from my Aztec C website at: http://www.clipshop.ca/Aztec This project is a complete build environment under AppleX for both the English and French Versions of "What Time Is It?". It does not contain the IBM Graphics and the intermediate files that were used to build the finished graphics that are provided with this project. I'll release all that separately if at all because that requires lots of explanation that really isn't related directly to the programming of this. I may already have done so by the time you are reading this. In deciding to release this source code as a working project, I just felt that to confuse an already complicated environment further by adding all sorts of graphics processing would distract you from understanding how the source code all gets put together into a program. You can read the document "WhatTimeIsIt.txt" for the usual user-level drivel or just run the program and read the source code to see how it works. This project also comes with working french and english Apple II emulator diskimages of the completed project for whatever diabolical amusement they may provide. Overlays Since memory is not abundant on the Apple //e I have broken this project into overlays. Overlays have always needed lots of fiddling because you need to make sure that they remain as small as possible. Common routines used by all overlays are stored in the main module. In this case, TIME.SYSTEM (time.c). Routines specific to an overlay are stored in that overlay. In this project, overlays are used in a couple or three ways. However, every overlay in this project occupies exactly the same area of memory, and each is called in its own turn from the main module TIME.SYSTEM (time.c). CINIT.OVR and PLOGO.OVR are initialization overlays. The code they use is not shared by the other modules. FLOGO.OVR is the french equivalent of PLOGO.OVR. When "What Time Is It?" starts-up it calls these. All this is pretty-well commented in TIME.C and further in the respective overlays' source code. MAINMENU.OVR is a navigational overlay (a switchboard of sorts) and is called after initialization from TIME.SYSTEM. But since there is no point in using memory when a menu choice is selected, this overlay comes and goes as required. When a menu choice is selected from MAINMENU.OVR the corresponding overlay for the menu choice is loaded. TIME0.OVR, TIME1.OVR, and TIME2.OVR are the overlays for activities selected from MAINMENU.OVR. Again, you can review the source code in time.c to see how this all works. Upon sucessful completion of the activities in TIME0.OVR, TIME1.OVR, and TIME2.OVR a respective reward overlay is called; either TIME0A.OVR, TIME1A.OVR, or TIME2A.OVR. English and French Versions As I said in the beginning, PLOGO.OVR and FLOGO.OVR are really the same program with English or French being set respectively within each. This is somewhat of a hack, and to see how the english and french versions are actually built, the MAKEFILE should be reviewed in addition to the source for for PLOGO and FLOGO. Another difference between the English and French Versions is the image libraries for each; TIME.RIB and FTIME.RIB. The only difference between these two libraries is the screen for MAINMENU.OVR; TIME.RIB contains an English screen and FTIME.RIB contains a French Screen. The third (and final) difference is in the English and French title screens; PLOG.RAG and FLOGO.RAG. Again, the MAKEFILE should prove informative for further info as to exactly what I do to build an English and French version of "What Time Is It?" by substituting the 3 English artifacts mentioned above with their French equivalents to build a French version. All this hacking might seem a little inelegant, but it was all done for various reasons, of which one was that the publisher did not want to provide both versions on the same disk so there was no requirement to switch between languages on the fly. Disk space was at a premium as well, as was memory so not mixing the versions in the same executable program distribution kept the disk size and memory usage to a reasonable minimum. So I hacked it this way, and delivered it this way, and since the finished product all worked I moved on. So what you have here is an English program that is patched when it is built to create a French Version with what I considered minimal effort at the time. Auxilliary Memory Perhaps the most valuable information in this project is how I use the upper RAM bank on the Apple //e to store and retrieve my graphics. Reviewing this source code and the G2 library source code that I provided with AppleX should clarify how this is all done. Clock Routines My clock routines are done using a fairly sparse table driven methodology, again in a an effort to run as quickly as possible with as little memory usage as possible. Exactly how this is done can be reviewed in the circlepoints routines that are in any of the TIMEO, TIME1, and TIME2 modules. The reason this code is repeated in each of those overlays goes back to saving memory by balancing overlays with each other and in the main module. If the main module gets too bulky then other overlays won't have room to run. I moved evrything around until it all fit, adding code and removing code as required. This is the way it ended-up working. MAKEFILE, Directories, and DiskImages I have arranged the build environment into a main directory and 3 subdirectories. The MAKEFILE depends on these subdirectories as well as the AppleX build environment which requires Windows XP. The main directory contains all the source code and this ReadMe file and its 2 associated text files, and the MAKEFILE and nothing else. The RES (resources) subdirectory is used in conjunction with the Makefile to create the English and French Versions from scratch. The ENGLISH and FRENCH subdirectories are the GOAL directories and a complete version of the program is created in each of these in their respective languages. The ENGLISH and FRENCH subdirectories also contain working DiskImages of the finished project. They also contain PRODOS 8 but no additional system files. Compatibility These programs have been used on real Apple //e's and Apple //e emulators in Windows XP. They have also been tried and true back in their development stage on Apple GS's and even on Macintoshes using the Apple //e emulators of the day. The Apple //e that I used to originally develop these on had a 5 MGHZ zip chip which was an accelator that replaced the 6502 processor that ran at 1 MGHZ. With the zip chip, my Apple //e ran quite as quickly as my old true- blue IBM-PC or so it almost seemed when it came to this sort of program. Most importantly these programs all behaved well whether run in an emulator or run in native mode. So depite the fact that the code is a little messier than it would be if I wrote it today, compatibility has never been an issue with these programs as far as I know. Final Comments So what you have here is a real full-blown commercial program of the flavour of the bygone Apple //e era complete with source code and some pretty fair architecture for its day. It's not really very complicated either, once you get into it, and if your were so inclined you could use this whole affair as the basis for your own programs of a similar nature. Since you are obviously reading this for some reason of interest, I do hope that my notes and this project satisfy whatever perverse reason that finds you playing with all this old stuff in the first place. Have Fun! Bill Buckels bbuckels@mts.net March 2008 (C) Copyright Bill Buckels 1991-2008 All Rights Reserved. End of ReadMe