        PocketAtari: The Windows CE Port of the Atari 800 Emulator.

(Last Update of this File: 30 Oct 06)

I. PURPOSE
------------------------------------------------------------------------------
This file describes the installation and compilation procedure for the Windows
CE port of the Atari800 emulator [1]. The port currently supports Pocket PC and
Smartphone devices deployed with the 2002 version of the OS, also known as
WCE300. It has also been tested on devices featuring version 2003 and Windows
Mobile 5 of the OS and runs just fine. Your mileage may vary. 

II. NEWS
------------------------------------------------------------------------------
The updated version of this port:

o Adds support for Smartphone devices.
  - Now supporting QVGA Smartphone devices.
  - Supports QVGA Landcape Smartphone devices. [NEW in 2.0.3]
  - Adds a popup virtual keyboard. [NEW in 2.0.3]
o Support for VGA displays.
o Includes interpolating downsampling filter for Smartphone displays.
o Keeps the backlight always on.

III. INSTALLING
------------------------------------------------------------------------------
To intall PocketAtari on your PocketPC/Smartphone device:

o Create a directory anywhere on your device (Smartphone users need a suitable
  file explorer application; else you can create it in the Start Menu folder).
o Copy the pocketatari.exe file there.
o (Optional) Older Windows CE devices also need GAPI from Microsoft [6]. Copy
  gx.dll into the folder as well.
o Copy the Atari OS ROM files in the same folder (see the FAQ for the ROMs).
o (Optional) Create a symbolic link to pocketatari.exe at 
  (IPSM)\Windows\Start Menu.
o You're good to go!

NOTE: The PocketAtari binary does not support older Palm devices (eg. wince 
2.11), but the source code should compile and run with no problems. If you 
can contribute a build for these devices contact me through [3].

IV. USING
------------------------------------------------------------------------------
Pocket Atari can operate in portrait, landscape and inverse landscape mode.
Port-specific options in the Windows CE version are:

o Virtual Joystick (in Controller Configuration, Pocket PC only)
  Enable joystick emulation with stylus.
o Enable Linear Filtering (in Display Settings)
  Use filtering for better image quality.

Controls for the different classes of devices:

a. Pocket PC
Use the displayed keyboard/menu to operate the emulator. In landscape modes
tap the bottom right corner of the atari screen to display the keyboard/menu.

b. Smartphone
Due to the lack of proper keyboard and pointing device, the emulated Atari features
are limited. You can play the majority of games though. Use the following keys:

Directional keys            : Simulate joystick 0                   $
Softkey A, Softkey B, 4, 6  : Fire joystick 0                       $
0                           : Return key
7                           : Option key
8                           : Select key
9                           : Start key
Softkey C (usually '*' key) : Show emulator menu                    $
Talk/Call/Green key         : Switch between the 3 display modes

For navigating the emulator menus use buttons marked with '$' above.

Pressing and holding the Softkey C for more than one (1) second during emulation
brings up the virtual Atari keyboard. Navigate with cursor keys to the desired
key and press Softkey A or B to inject one keystroke into the emulator.

TIP: In some demos, pressing the SHIFT key skips the current part. In the virtual
     keyboard the SHIFT key is a toggle, so select also another key. The SHIFT
     keycode will register just fine.

NOTE 1 : Functionality of Softkey A, Softkey B and * keys may be attributed
         differently according to the drivers of your cellphone.
NOTE 2 : Until we get a fully modifiable controller configuration option in
         Atari800, you have to live with the preassigned keys. As an exception,
         some smartphones have reported problems with the simultaneous use of
         the fire keys and the directional pad. I have included an option to
         exchange the functionality of the Softkey B and C keys. This should be
         considered as an UNSUPPORTED option which will go away in the future.
         To enable it include the following line in your atari800.cfg file:
         WCE_SMARTPHONE_KBHACK=1
         Also note that this behavior is enabled by default for QVGA Landscape
         Smartphone devices, due to the possible lack of a Softkey C.

V. COMPILING
------------------------------------------------------------------------------
You will need the following tools:

o Microsoft Embedded Visual Tools 3.0 [7].
o GAPI emulation [4] for the emulators.
o The zlibce library [5].

Create a folder named zlib inside the src/wince directory. Copy zconf.h
and zlib.h in zlib/. Create two folders named arm and x86 (src/wince/zlib/arm
and src/wince/zlib/x86). Copy the appropriate zlibce.lib files in these
directories. Don't forget to upload gx.dll (if needed) and zlibce.dll to your 
emulator. Also for older Smartphones you'll have to compile yourself a version of
the gx.dll using the GAPI emulator files. The Smartphone resolution is 176x220
pixels with 16bpp (either 565 or 555 RGB configurations).

NOTE 1 : If you cannot open the project file "PocketAtari.vcp" from the source
         tarball or CVS checkout, make sure that it is in CR+LF format (and not
         just LF). A utility like unix2dos can do the trick.

NOTE 2 : PocketAtari can also compile OK using evc4 or Visual Studio 2005.

VI. HISTORY
------------------------------------------------------------------------------
The Pocket PC port was originally done by Vasyl Tsvirkunov [2].
Kostas Nakos [3] updated the port and added support for Smartphone devices.
Many thanks to Vasyl for providing us with a stable codebase!

VII. CONTACT
------------------------------------------------------------------------------
Please visit my Atari800 page [3] for fresh builds and news.
To report bugs or request new features you can email me at: knakos@gmail.com
Also visit Vasyl's Atari800 page [2] and check out the links for more of his work.
For inquiries about the Pocket PC/Smartphone port or the emulator in general
you can also take a look at the Atari800-users mailing list available at [1].


                                                               Enjoy!
                                                               Kostas Nakos,
                                                               31/08/05
                                                               Athens, Greece


VIII. REFERENCES
------------------------------------------------------------------------------
[1] Atari800 project homepage
    http://atari800.github.io/
[2] Vasyl Tsvirkunov's Atari800 page
    http://pocketatari.retrogames.com
[3] Kostas Nakos' Atari800 page
    http://pocketatari.atari.org
[4] GAPI emulation
    http://pocketfrog.droneship.com/
[5] zlib for Windows CE
    http://www.tenik.co.jp/~adachi/wince/
[6] Microsoft GAPI 1.2
    http://www.microsoft.com/downloads/details.aspx?FamilyID=d9879b0e-4ef1-4049-9c61-e758933d84c4&displaylang=en
[7] Microsoft eMbedded Visual Tools 3.0 
    http://msdn.microsoft.com/mobility/windowsmobile/downloads/default.aspx
