Commodore 64 Emulator Version 0.4 Documentation
(C) 1993-4 Earle F. Philhower III (st916w9r@dunx1.ocs.drexel.edu)

(Also glance over the version 0.3, 0.2, 0.1 readmes for more information)
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
Table Of Contents


	1)	What's New In This Release?
	
	2)  Quick-Start Guide
		a)  Keyboard
		b)  Disk Images
		c)  Tape Images
		d)  RAM Images
		e)  Preferences
	
	3)  Frequently Asked Questions
	
	4)  How Can I Help?

	5)  Credits and Eulogy :<

-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
1)  WHAT'S NEW IN THIS RELEASE?

General:
	Faster Integrated C 6510 processor
		(about 5% faster than 68k coded)
	Power PC native version (same source as 68k)
	Included undocumented opcodes
	Cleaner source code in some files
	There's some kind of documentation!

Video:
	Multicolor Mode support
	B/W sprite handling has been fixed
	Double sized display

Interface:
	Dragging one VIC window drags both
	About box centered
	Should switch cursor better
	Loading a RAM image updates display

Bugs:
	The color VIC window sometimes goes off into the upper-left hand corner
	of the screen and crashed the C64.  I haven't a clue as to why, as the BW
	version doesn't exhibit this behavior.

	There have been some problems with some international setups and EC040 Macs
	(the drain bramaged variety Apple sells in the Performa line)  I don't have
	any way of testing where the program is dying, since Drexel doesn't have
	those.


-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
2)  QUICK START GUIDE

1.  First figure out which executable you need to run:  If you have a PPC Mac
	use "Commodore 64 PPC", otherwise use "Commodore 64"
	[PPC owners can also use the "Commodore 64" execuatble, only it will run
	 much, much, much, slower]
	 
2.  Once you've got it running you're sitting at a virtual C=64!  That simple!
	Device #8 is the virtual 1541 drive.  Device #9 is an interface into the Mac
	filesystem (not fully complete, but you can load and save files to the
	directory where Mac64 executable resides).  Device #4 is a printer whose output
	goes into a file called "PRINTER" in the startup directory  (Not fully done
	either).
	
3.  To toggle between "Running" and "Suspended" modes on the C64 window, just
	click in the window.  When you're running the cursor is normally a C=, and
	when you're suspended it is normally a standard arrow.

--
Keyboard

	They keyboard mappings are very simple.  All letters and numbers are done
	as you would expect.  However the FUNCTION keys are accessed via an
	Option-# press.  (I.e. F-7 = Option-7)
	
	Cursor keys work (you DON'T need to SHIFT-UP to go down...)

	Some of the Control keys are implemented via CTRL-x.  If it doesn't work
	for you then I've not added that key!

						DELETE	=	C64 delete
						ESC	=	RUN/STOP
						`	=	RUN/STOP-RESTORE
				
	When in emulation mode, COMMAND-<key> is in effect, and you can bring up
	menus w/o stopping the emulation.
--
Disk Images

	In order to access a D64 disk image (which is nothing more than a raw sector
	dump of a Commodore 1541 format floppy disk) you can either:
	
		a.  Select "Attach Floppy Image..." from the "Devices" menu to "insert"
			a pre-made diskette into the virtual 1541 (device #8)
			
		b.  Double-Click on a D64 image (if it has the proper icon (5.25" disk))
			to insert it...
			
		c.  Select "Create Floppy Image..." from the "Devices" menu to "format"
			a new diskette.  You'll have to select a *Macintosh* file name to
			create.  It'll automatically "insert" the disk for you.
--
Tape Images

	A lot of single file games are being distributed in T64 format.  To load
	a T64(tape image) file into the emulator, you can either:
	
		a.  Select "Load Tape File..." from the "Devices" menu.  Select the
			tape and it will be loaded into C= memory.  You *MUST* type "RUN"
			in the C64 window to start the program, once it's loaded.
		
		b.  Double click on the icon of a T64 image (It should look just like
			an audio cassette) to load it.  Again, you must "RUN" it to make
			it go.
	
	There is no way currently to make T64 images from the emulator.
--
RAM Images

	A RAM image is a complete saved state of the Commodore 64 window.  If you
	know what a "freeze" cartridge is, you get the idea.  Basically the entire
	machine (RAM, processor) are stored in a file which can be later accessed.
	So you can load up Zork (assuming it works...:[) go on for an hour, save
	a RAM image.  Later you can resume the game by loading the RAM image.
	
	To save a RAM image:
		Select "Save RAM Image..." from the "File" menu.  Enter a name and
		viola!  RAM image is saved.
	
	To load a RAM image you can either:
		
		a.  Select "Load RAM Image..." from the "File" menu.  Select the file
			and the processor will be restored to the saved state.
		
		b.  Double-click on a RAM image icon (It looks like an IC)
		
	Note that the processor must be running in order to make the program go
	after loading it.
--
Preferences

	The preferences dialog, accessible from the "File" menu allows you to
	change the way the Commodore 64 is emulated.  You can switch between a
	color(slow) and b/w(fast) version of the VIC, choose between three
	different processor emulations, and other neato stuff.

Video:
	Byte Align Window:
		This toggles between making the window appear on an 8-bit boundary.
		On machines set up to run with a monitor depth of 1 pixel (b/w) you
		can get a significant speed increase by doing this.  When you have
		the monitor set up to display in color, this option will NOT speed
		up the display.  Useful on "aquarium" Macs.
	
	B/W or Color:
		Chooses the type of video output from the Commodore you want.  The
		color version only runs on machines with color Quickdraw (but will NOT
		crash your machine if you don't).  B/W is relatively fast and more
		debugged than the color version.  The color version is exceedingly slow
		on almost any machine, but supports hi-res, color, sprites, etc.
	
	Double Size:
		Doubles the size of the video display.  If you have a 640x480 monitor
		you can display the double-sized color or BW window so you don't get
		eyestrain.  Note that this is MUCH slower than non-double size.
	
Processor:
	Skip RAM Test:
		Patches the KERNEL ROMs in memory to make the Commodore 64 skip the
		memory test.  It's 100% compatible with any piece of software that will
		run on the emulator.  Also makes the reset MUCH faster.
	
	68k or C or Integrated C:
		Allows you to choose between different emulations for the 6510, the
		microprocessor at the heart of the Commodore 64.  I recommend using
		the "Integrated C" on *ALL* platforms, since it is much faster and
		includes undocumented opcodes.  The 68k is just slightly slower than
		the Integrated C, and the plain old C is about 25% slower.
		Note that on the PPC version 68k=Integrated C.


-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
3)  FREQUENTLY ASKED QUESTIONS

*****
Getting in touch with me about this emulator:

	Send all email questions, comments, suggestions to:
					st916w9r@dunx1.ocs.drexel.edu
	PLEASE INCLUDE THE VERSION OF THE EMULATOR THAT YOU ARE USING IN YOUR
	FIRST MESSAGE.  I'd also like to hear where you got the emulator from
	(AOL, internet, BBS, etc.)
*****
Getting the latest version:
	I will be storing the latset revisions on _the premier_ Commodore archive:
								watson.mbb.sfu.ca
	Access it via anonymous FTP, go to the "emulator" directory.  The latest
	version will always be called:
								MAC64-xx.HQX
*****
XXXXXX won't run:
	Yup.  You're probably right.  The emulator right now is built for speed and
	ease-of-comprehension.  Either wait for a later version, or reprogram what you
	have...
*****
Are there any other Commodore emulators:
	By far the best Commodore 64 emulator available for the IBM PC is:
								C64S09x.ZIP
	You can get it off of the "watson..." site mentioned above.  Also get
	the following file:			ROMCODE.C64
	
	For the Macintosh, you're running the only emulator available, so it's the
	best!!!
	
	If you've got X11 and some time on your hands you can get X64, a really
	good emulator under UNIX & X11:
								x64-0.2.x.tar.gz
	In fact, I'm using some code from X64 in my current emulator!
*****
Q.  What's a "xxx.D64" or "xxx.T64" file?

A.  A *.D64 file is a binary image of a 1541 floppy disk.  To use it with the
    emulator, use "Attach Floppy Image" from the Devices menu.  Just use the
    regular "LOAD "xxxxx",8" commands in C64 BASIC to load any of the programs
    on the disk.  Enter "RUN <enter>" to make the program RUN after LOADing it.
    
    A *.T64 file is just a hacked copy of a C64 file.  In theory it supports
    storing multiple programs per image, but as of now 99.9% of the images are
    only holding one file.  To load a T64 file, select "Load Tape Image" from
    the Devices menu.  Then type "RUN" to make the program go.
*****
Q.  How can I get 1541 disks from my Commodore to my Mac?

A1. You can't.  Use a PC with "disk64e" or "x1541" to transfer the files to a
    IBM format floppy, the use PC Exchange to copy the files from the IBM
    disk to your Mac.
A2. Use a RS232 converter from your C64's user port and a Null-Modem cable
    between the converter and the Mac.  *DO NOT CONNECT YOUR C64 TO YOUR MAC/PC
    WITHOUT AN RS232 CONVERTER.  YOU WILL DAMAGE YOUR C64 BY DOING SO!*
*****
Q.  I want to do some work with your code.  What should I do if I want my
    changes to be inclued in one of your later C64 releases?
    
A.  I'm very open to changes/additions to my program.  In fact, almost 30% of
    the code is now from others.  If you've done some work send me some mail
    at Drexel, and *comment* any changes you make.  It'll make my work much
    easier!  And, of course, you've got to allow distribution of your changes
    unde the GNU GPL.
*****
Q.  Is there a joystick?

A.  No.  Not yet.  Right now I've got to get the games to work...


-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
4)  HOW CAN YOU HELP?

	If you've got the talent and the time, go through the source code.  Find
	and eradicate any bugs you find.  Add any features you think should be
	added.  And send all of your changes to me at my email address.
	
	I'm more than happy to assist in any work you're doing on the emulator,
	just don't start asking me to do your CompSci homework!
	
	UPLOAD THIS TO AOL SO THAT I DON'T KEEP GETTING 10 MESSAGES A DAY FROM
	PEOPLE WHO DON'T HAVE INTERNET ACCESS ASKING ME TO MAIL THEM MY PROGRAM!


-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
5)  CREDITS AND EULOGY   :[

	Well, Commodore International is dead.  A moment of silence while the
	credits roll, please:
	
    68000 6510 Simulator:  George T. Talbot        <ugtalbot@mcs.drexel.edu>
    Color VIC Display:     Eric M. Stadtherr          <emstadth@iastate.edu>
	MetroWerks, PPC:       Johnathon L. Suker             <jlsuker@ucis.edu>
    Major Testing:         Georg Schwarz   <georg@marie.physik.tu-berlin.de>
    Optimization, PPC:     Peter Creath              <peterc@gnu.ai.mit.edu>
    Tape Image Format:     Werner Zsolt               <mttto22@ursus.bke.hu>

     (If I've forgotten you, drop me a line and I'll correct my oversight)


-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
"Commodore 64 Emulator...
It's not much, but it's the *only* Commodore 64 you can run on your Mac!"

Any user suggestions, bug-fixes, updates please email me at Drexel Univ.
(st916w9r@dunx1.ocs.drexel.edu).  A 1.0 release doesn't seem to be too far
away, as most things are already implemented!  [Yeah, right...hahahaha]

You can also get in contact with me on ISCA BBS [telnet whip.isca.uiowa.edu]
under the handle (suprise) "Earle."  I frequent the "Antique Computers" forum.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

(C) 1993-4 Earle F. Philhower III (st916w9r@dunx1.ocs.drexel.edu)
