				****************
				*   GtkTiEmu   *
				****************




For the installation procedure, see INSTALL.linux
For a more specific README, see README.linux or README.win32


+-------------+
| DESCRIPTION |
+-------------+

GtkTiEmu is a program allowing a PC to emulate a TI calculator (at least the
TI89/92/92+ types for the moment).
It uses GTK+ (the Gimp ToolKit, http://www.gimp.org/gtk) for the GUI and the SDL (SimpleDirectmedia Layer) for the display. 
It works on Linux and Windows platforms actually.

All link cables are supported by the link port: parallel, serial, 
Black TI Graph Link, Gray TI Graph Link and the (fast)AVRlink.

GtkTiEmu is based on XTiger, the original TI emulator for Linux (see the AUTHORS file for more details) which uses the 68k emulation core from UAE (The Ultimate Amiga Emulator).
It also uses the libticables library.


+----------+
| FEATURES |
+----------+

Some features:

o Works on 8, 16, 24/32 planes display (256, 65565, 16M/True colors)
o Easy to use thanks to a GUI developped with GTK+
o The ability to save the emulator state
o Full linkport emulation (all link cables, even virtual)
o Works with Fargo
o Works with 1Mb & 2Mb ROMS, 128 or 256k memory (but FLASH Apps/OS does not work)
o Nice debugger (memory, breakpoints, traps, vectors, ...)
o Constrast emulated (Try [Alt] + [+] & [-])
o Useable through a Netscape/IE plugin (under development)
o Pretty fast
o Sreenshot of LCD or calculator in several images format (JPG/PCX/XPM/BMP)
o TI keyboard useable directly from PC keyboard or with the mouse on the skin (VTi's skins)


+---------------------+
| SYSTEM REQUIREMENTS |
+---------------------+

You will need a PC Intel computer. A 100MHz processor is a minimum.
GtkTiEmu uses roughly 10MB of RAM.
Nethertheless, it is fast (it starts in 10 seconds on a PC166/64MB). 


+------------------+
| ROMDUMPS & FARGO |
+------------------+

To run this emulator you will need a ROM dump. As this file is
copyrighted by Texas Instrument it will never be distributed with
the emulator. To get a ROM dump, you can use TiLP or any other
ROM dumping program. TiLP may be interessant because it can be virtually linked
with the emulator.
A TI92 requires FargoII for getting a ROM dump.

If you want to run Fargo on the emulator, you will need to get
a backup, put the fargo core inside (converted with
"putfargo") and send it to the emulator.


+-----------------+
| HOW TO USE IT ? |
+-----------------+

When you launch it, GtkTiEmu take some a while for initializing it. Once you 
have launched, you should see a window with the look of your calculator. 
You can either click with the left button on a TI key, either press the 
correspondant key of your PC keyboard.

Else, the right button of your mouse let you access a popup menu which contains
all you need (I hope !) for configuring/using the emulator.


+------------------+
| KEYBOARD MAPPING |
+------------------+

The keyboard mapping is the same as VTi (since we use VTi's skins), the well 
known TI emulator for Windows.

TI92       PC
---------  ------------
[Hand]     [Caps Lock]
[SHIFT]    [Shift]
[ON]       [Sroll Lock]
[DIAMOND]  [Ctrl]
[2ND]      [Alt]
[STO>]     [Tab]
[SIN]      [Insert]
[COS]      [Home]
[TAN]      [Page Up]
[LN]       [End]
[CLEAR]    [Suppr]
[MODE]     [Page Down]
[APPS]     [Print Scrn]
[(-)]      [<]
[Theta]    [;]
[+]        [+]
[-]        [-]
[X]        [*]
[Div]      [/]
[^]        []
[(]        [[]
[)]        []]

Letters, Numbers, Cursormovement, F1-F8 + some others are the
same keys on both keyboards

Special Keys

[F9]       Enter Debugger
[F10]      Do a screen capture


+-------------------+
| RIGHT BUTTON MENU |
+-------------------+

Rem: the SDL version have a small and tricky bug: you have to double-click the menuitem for activating it.
The right button menu give you access to the functionnalities of the emulator. If you let your mouse on the item during some while, a tooltip will appear.
This menu is organized as follow:

- Send file to GtkTiEmu: load a file and transfer it into the emulator. Not implemented yet. Instead, you will have to use the virtual link for the moment.
- Command shell (Linux only): display a prompt in the console for directly entering some commands.
- Config: load/save the current configuration in the config file (~/.gtktiemu ou gtktiemu.ini). The current state is not saved but loaded if it has been previously saved.
- Link options: configure the link port
- Enter debugger: see the DEBUGGER section further in the text
- Set program entry breakpoint: not implemented yet
- Reset calc: reset the calculator (RAM, FLASH: all !).
- Calculator state: save/load the current state or load the latest saved stated
- Emulator options: 
	Speed: for tuning GtkTiEmu. Only the 'Sync' item is implemented.
	Colors: allows you to choose the number of grayscales as well as the colors
	themselves
	Keys: not implemented yet
- Skin for current calc: you can choose to display the emulator with a skin or only
the LCD display. You can also press 'Alt+Enter' for toggling the full-screen mode
- Screenshot: do a screenshot of the LCD display. The screenshot file is automatically incremented.
- RAM: dump the RAM content into a file. The file is a text file and contains
an hexadecimal & character dump.
- ROM:
	Dump ROM: dump the ROM content into a file. The file is a text file and
	contains an hexadecimal & character dump. Beware, this may take some time
	and space disk for writing the file (roughly 10 MB).
	ROM file: select a ROM image to load
	Update file: select a TI FLASH upgrade file to load
	Set ROM: list all available ROMs (installed in the ROMs directory) as well
	as a lot of miscellaneous informations.
	Convert into ROM: allows you to convert a TI's FLASH upgrade into a ROM 
	image. Useful for emulating a calculator without a ROM image.
	Remark: the converted ROM image will not have a boot block and so you will 
	not be able to use some FLASH features.
- About: display the logo and the license as well as misc informations.
- Infos: some informations about the calc and the developper
- Exit and save state: save the current state and quit
- Exit without saving state: exit immediately without saving the curren state.


+--------------------+
| LINKPORT EMULATION |
+--------------------+

GtkTiEmu emulates the linkport in two ways. First through a link cable 
(hardware or virtual).
GtkTiEmu can communicate with the hardware (parallel, serial, ... link cable) or virtually (TiLP, VTi, another GtkTiEmu application).

Remark about virtual links: you have the choice between the GtkTiEmu and 
the VTi virtual link.
For Windows users: the Vti virtual link allows you to make GtkTiEmu 
communicate with VTi. It provides also a different linking method of the 
GtkTiEmu virtual link.
For Linux users: the 2 possible virtual link are useable.
Simply choose the best or the fastest.

For the GtkTiEmu virtual link, the emulator must be set on the channel #0 and the linking program on the channel #1.

Else, GtkTiEmu can not load files directly from disk. It will be implemented later.
Sorry (I know that virtual linking is a bit slow) !
// to do...
//It can also load files directly from disc and emulate the TI92
//protocol to load them into the emulator. This is accomplished
//from the commandstate (see below) with the "load" command
//(and also the "files" command which is perhaps less obvious).


+----------+
| DEBUGGER |
+----------+

It does not work in the Win32 version due to a memory bug.

For quickly launch the debugger, press F9. Else, you can use the right button menu.
The debugger allows you to monitor the code and registers, place several kind of breakpoints (addresses, traps, exceptions, data, ...) and also single step your instructions.

Remark: there is a popup menu available on the 'Code' and 'Memory' frames. Simply press your right button mouse for displaying it !

Currently, the 'Log' menu is not implemented.


+-------------+
| SCREENSHOTS |
+-------------+

Simply press F10 for doing a screenshot with the current options. The different options can be easily modified in the 'Screenshot options' dialog box.
You have the choice between several file formats: PCX, XPM, JPG and BMP (SDL/Win32 and SDL/Linux only).

The screenshot filename is automatically incremented whenever you do a screenshot.


+--------------+
| COMMAND LINE |
+--------------+

All the informations about the command line and the configuration file format 
(~/.gtktiemu or gtktiemu.ini) are available in:
-  the manpage for the Linux users ('man gtktiemu'),
-  the Manpage.txt file for the Windows users.


+--------+
| THANKS |
+--------+

Jonas Minnberg for making (X)Tiger from which we have developped GtkTiEmu.
Rusty Wagner for the calculator skins.


+------+
| BUGS |
+------+

- FLASH archive works but not FLASH Apps/OS
- X11 version seems to not start in 8 bit mode
- X11 & SDL version have not been tested in 32 bit mode (I wasn't be able to
  to do it)

If you find a bug, please give your:
- calc type
- ROM version & HW type
- the size and color depth of your screen (Linux users can use the xdpyinfo
  command)
- any infos you think interessant.
Please report any bugs at <rlievin@mail.com>.


+------+
| TODO |
+------+

See the TODO file for more informations.
Nethertheless, if you like programming in GTK+, you could develop a skin editor for Linux. Mail me, you will have all my help !


+-----------+
| COPYRIGHT |
+-----------+

gtktiemu and the libti68k library are Copyright (C) 2000-2001 by Romain Lievin 
<rlievin@mail.com> and Thomas Corvazier <corvazier@yahoo.com>
libticables is Copyright (c) 1999-2001 by Romain Lievin <rlievin@mail.com>

The libti68k library is based on the XTiger emulator (see AUTHORS for more 
details) which is based on UAE (Universal Amiga Emulator).


Copying is allowed under the terms of GNU General Public License (LGPL).  
See the file COPYING for more details.
