Provided by: apple2_0.7.4-3_i386 bug

NAME

       apple2, xapple2 - Apple ][+ and //e emulator

SYNOPSIS

       apple2

       xapple2 [ -noshm ]

DESCRIPTION

       apple2  (svgalib)  and  xapple2  (X11) both emulate a 64k Apple ][+ and
       128k Apple //e computer (the latter only if //e support  compiled  in).
       To  use  the  emulator you need to acquire the original ][+ and //e ROM
       files which are not distributed due to copyright reasons.  The emulator
       reads  standard  143360-byte and 232960-byte disk image files with .dsk
       and .nib suffixes respectively.  You can also change  any  images  with
       the extension .do to .dsk and they will work too.

       There are only a few command line options:

       -noshm This  forces  the  X11  version to not use the MITSHM extension.
              This may degrade the speed of the emulator but allow you to  run
              it remote.

THE .apple2 FILE

       The emulator reads user preferences from a .apple2 file located in your
       home directory.  Copy the .apple2 file that comes distributed with  the
       emulator  to your home directory.  You can edit the settings using your
       favorite editor, but most of the settings can be  tweaked  from  within
       the emulator (see menus section below).

       speed  Speed  of  emulation,  1  -  XXX.   (Actually this is an inverse
              delay-loop counter).  1 is slow, and XXX is as fast as  can  be.
              A  delay loop is needed to bring the emulation rate down to near
              what would be considered a normal Apple ][ speed.  The max speed
              value should be determined by YOU when you compile the emulator.
              For <= 100Mhz Pentium systems, I personally like a max value  of
              100  with  a  normal  apple  ][ speed somewhere in the 70s.  For
              faster machines, try larger ranges.

       mode   Starting emulation mode.   One  of  "][+",  "][+  undocumented",
              "//e".   You can also dynamically change the emulation mode from
              within the emulator.

       disk path
              Toplevel path of  disk  images  directory.   Personally  I  like
              /usr/local/games/apple2/disks.

       color  Black/white, lazy color, color, lazy interpolated, interpolated.

       sound  Off, pc speaker.

       joystick
              Off, linear, pc joystick.

       joystick range
              2  -  256.  Range of the joystick values.  Good settings are 256
              and sometimes 128, with centers  at  128  and  64  respectively.
              This often depends on the game.

       origin_x
              X coordinate origin.  128 is good for many games with a range of
              256.  Others like 64 with a range of 128.

       origin_y
              Y coordinate origin.  128 is good for many games with a range of
              256.  Others like 64 with a range of 128.

       pc joystick parms
              You  can  configure  this  from within the emulator.  Select the
              'Calibrate' option from the F10 menu.  If the emulator complains
              that it cannot open the joystick device, make sure the module is
              loaded.  This option  is  only  valid  if  you've  compiled  the
              emulator with -DPC_JOYSTICK.

       sensitivity
              1%  -  100%.  This value is used for the emulated joystick using
              the numeric keypad.

       system path
              The directory holding the rom files.  The emulator won't run  if
              this  is  not set properly.  You can only change this by editing
              the .apple2 file.

       So here is an example .apple2 file:
            speed = 72
            mode = ][+
            disk path = /usr/local/games/apple2/disks
            color = interpolated
            sound = pc speaker
            joystick = pc joystick
            joystick range = 256
            origin_x = 128
            origin_y = 128
            pc joystick parms = 767 693 1344 28 1454 28 13
            sensitivity = 13%
            system path = /usr/local/games/apple2/rom

ROM FILES

       The emulator requires several ROM files to run.

       apple_II.rom
              You need this file for basic ][+ emulation.  It contains the 12K
              ROM  of  your  Apple ][+. It is not distributed due to copyright
              issues, so you have to get this file on your own.  If  you  have
              been  running  another  apple2 emulator, you can most likely use
              its ROM files directly.  This file  is  a  memory  dump  of  the
              consecutive  addresses from D000 to FFFF of the Apple ][+.  This
              file  may  also  be  named  apple.rom  or  apple2.rom,  but   is
              referenced internally as apple_II.rom.

       slot6.rom
              You  need  this  file for basic disk drive emulation.  It is 256
              byte memory dump of the consecutive addresses from C600 to C6FF.
              This  file  is  not  distributed  again due to copyright issues.
              This file may also be named controller.rom,  but  is  referenced
              internally as slot6.rom.

       apple_IIe.rom
              If  //e  support was not compiled into the emulator, then you do
              not need this file.  It is the 32K ROM of your 128k Apple //e, a
              dump  of  main  memory (bank 0) addresses C000-FFFF concatenated
              with auxiliary memory (bank 1) addresses C000-FFFF.  Because the
              apple_IIe.rom  contains  the  C600  slot,  you can construct the
              slot6.rom file from this one. The apple_IIe.rom file may also be
              named apple2e.rom but is referenced internally as apple_IIe.rom.

       character.rom
              A  2048  byte  ][+ character rom file.  This file is distributed
              with the emulator.

DISK IMAGES

       The emulator reads standard DOS3.3-order 143360 byte '.dsk' images  and
       raw-nibble  232960  byte '.nib' images.  The emulator can handle images
       which are gzip'ed as long as the suffixes are '.dsk.gz'  and  '.nib.gz'
       respectively.   The emulator simply assumes that /bin/gzip is available
       to compress/decompress these images in place as  needed  and  that  you
       have permission to do so.

       The  images  are  raw  binary dumps, containing the tracks from 0 to 34
       from the original 5.25 disk.   For  the  standard  143360  byte  '.dsk'
       format  each  track  is partitioned into sectors of 256 bytes, numbered
       from 0 to 15.

       The raw nibblized 232960-byte images are usually made of programs  that
       have  non-standard  formatting  as  a  means  of  copy protection.  The
       nibblized format attempts to preserve the non-standard format,  and  so
       defeats the copy protection without "cracking" the program.

       To  transfer Apple ][ diskettes into one of these formats requires that
       you own an original Apple ][. Since the drives provided by the IBM PC's
       are  not  compatible  with  the  original  Apple ][ drives there are no
       conversion programs directly available. If you have used other Apple ][
       emulators it is most likely that the files will work with this emulator
       too. For more information on  Apple  ][  disk  formats  and  such,  see
       Beneath  Apple  DOS by Don Worth and Pieter Lechner, published long ago
       by Quality Software.

EMULATOR KEYS/MENUS

       F1     Interface to switch  disk  in  Drive  A,  Slot  6.   Arrow  keys
              navigate  the  selection.  If the disk highlighted is already in
              the drive, it will have a <rw1>  or  <r1>  tag  after  the  name
              indicating  read/write or read-only access.  Select this disk to
              eject it.  To select a disk, you can  press  'w'  or  RETURN  to
              insert it into the drive.  Pressing 'w' will attempt to open the
              disk as read/write (if you have permission to do so).   Pressing
              RETURN  defaults  to  opening  the disk read-only.  Press ESC to
              accept current settings and exit the menu.

       F2     Interface to switch disk in Drive B, Slot 6.  Same  controls  as
              for F1.

       F4     Pause the emulation.  The Pause/Break key will also work.  Hit a
              key to resume.

       F5     Display the Apple ][+ or //e keyboard layout.

       F7     Enter the Debugger console (if this support  was  compiled  into
              the program).  See the file DEBUGGER that came with the emulator
              for command information.

       F9     Toggles between maximum speed and  configured  speed.   This  is
              useful  to  'fastboot'  programs,  and  then slip back to normal
              Apple ][ speed.

       F10    General parameter settings  menu,  including  the  all-important
              QUIT  option.   You  can  edit  most  of  the parameters in your
              .apple2 file from this menu.  Two options worth  mentioning  are
              the  'Calibrate'  and 'JS Sample' options.  'Calibrate' lets you
              calibrate the PC Joystick device.  'JS Sample' lets you set  the
              sample rate of the PC Joystick device.  'Save' lets you save the
              settings to your .apple2 file.

       Special Keys
              The key  combination  Ctrl-'PrintScrn/SysReq'  will  reboot  the
              machine.   The  Ctrl-'Pause/Break'  combination  will  reset the
              machine.   Remember  that   'Pause/Break'   alone   will   pause
              emulation.    AltLeft   and  AltRight  keys  correspond  to  the
              OpenApple and ClosedApple keys (joystick buttons 0 & 1).   NOTE:
              In  //e  mode  try  Ctrl-AltRight-'Pause/Break'  sequence  for a
              system self-test.  The  numeric  keypad  is  used  for  emulated
              joystick movement.

BUGS AND STUFF

       See the PROBLEMS file that came with the code.

       Using  the  joystick  for  some disk images is problematic.  Apparently
       there is a bug in Apple ]['s where reading  values  from  the  joystick
       ports   too   quickly   results   in   a  smaller  value  than  normal.
       Unfortunately the emulator doesn't emulate this bug in the machine, but
       you  can  mostly  get  the  same  effect  by  changing the range of the
       joystick.  For instance, games like Space Rogue  and  Airheart  like  a
       range  of 0x80 with the center around 0x40.  Most other games will like
       a range of 0x100 with the center around 0x80.

       Under X, you may notice that some keys are not  working  as  advertised
       (Pause/Break  as  reboot  for instance).  Make sure that these keys are
       mapped.  (Run xmodmap -pke for the current mapping).

MORE INFO

       More   information   is   available   in    the    online    newsgroups
       comp.emulators.apple2, and comp.sys.apple2.

       See also:

       Apple //e Technical Reference Manual

       Beneath Apple DOS

       Beneath Apple ProDOS

AUTHORS

       Apple  //e  support  and  revisions  v006,  v005,  v004,  v003 by Aaron
       Culliney (aculline@bbn.com).  Revision v002 by Stephen  Lee.   Original
       version(s) by Alexander Jean-Claude Bottema.