DosBox 0.72-4 for GP2X by Pickle/Hitnrun with the ARM dynarec by M_HT

** About DOS Box **
-----------------
DOSBox emulates an Intel x86 PC, complete with sound, graphics, mouse, modem, etc.,
necessary for running many old DOS games that simply cannot be run on modern PCs and operating systems,
such as Microsoft Windows 2000, Windows XP, Linux and FreeBSD

** Summary **
-------------
0.72-1 First Release:
What started as a simple test to recompile dosbox with a touchscreen enabled SDL lib turned into much more. As i dived
into it I found that dosbox unmodified crashed most of the time with a obsure glib error (which was also a common behavior of
previous GP2X compilations.) After some help from the GP2X community I made some changes that lowered the memory requirement
but wouldnt effect game compatibility. The crashes were gone and almost every game attempted now worked. Then it was
back to the touchscreen. The initial linking in the SDL lib the touchscreen did work but was very glitchy. I didnt
have a F200, but a tester Hitnrun did. He was able to debug the code and inject the touchscreen position direct into
dosbox. The result is a almost perfect touchscreen experience. I also did some small fixes that have been long coming, such
disabling the SDL mouse cursor, and profiling to optimize the binary, changing  some of the default settings. Hitnrun also
added some neat features zoom and the OSD (show cycles, frameskip, exe name, fps).
Performance increases may not be large, but with this release functionality was the goal. End of the story? Not quite there
is still something left and thats the ARM dynarec. This is last improvement that I see dosbox benefiting from, and it would 
be a major benefit. (It would also benefit other ARM devices, such as Pandora)

0.72-2 Second Release:
Well it just wont stop. The requests for mouse and a virtual keyboard drove me to actually adding them. Ive added both features
and hopefully they will be of benefit. Hitnrun also corrected the need to have fullscreen for 320x200 games using the
touchscreen. Now these games should give correct touchscreen positions. I also attempted to fix flickering issues with the
OSD's. It's better now, but there are a little bit of flickering that occurs. I did not profile this version, it is questionable if
it really made a difference.

0.72-3 Third Release
So the second version wasnt as polished as I anticipated. So this version has a few bug fixes. The OSD's no longer have any flicker,
the mouse emulation was fixed, the colors section for the OSD was fixed and improved. Rolled back all memory savers expect the TLB
change. New feature was added to save cycles/frameskip/OSD color selections to the dosbox.conf while in dosbox.
This version has been tested pretty well.

0.72-4 Fourth Release
Well the updates just keep coming. M_HT has finished his ARM backend dynamic recomplier, cant thank him enough for getting it to work.
Senor Quack has added some fixes and overall improvements to the touchscreen code in Paeryn's SDL library. Ive also have some of my own
fixes to my code.
Overall I think this will be the final version.

0.72-5 Fifth Release
M_HT made some changes the dynamic core code yielding more performance.
You can find more info here: http://members.chello.sk/apauer/dosbox2/dosbox2.html

Default Settings: (if not specified in the dosbox.conf)
machine          =vga
memory           =8mb
frameskip        =0
scaler           =none (SDL will still down scale anything larger than 320x240)
core             =simple (this is should be set to dynamic or auto, these will be slighly faster than the simple/full cores)
cycles           =auto
cycleup/down     =100
all sample rates =11025
audio buffer     =512
prebuffer        =10
soundblaster     =sb1
joystick         =none (never change this)

** GP2X Button Mappings **
--------------------------
UP              (0)	key 256
UPLEFT          (1)	key 257
LEFT            (2)	key 258
DOWNLEFT        (3)	key 259
DOWN            (4)	key 260
DOWNRIGHT       (5)	key 261
RIGHT           (6)	key 262
UPRIGHT         (7)	key 263
START           (8)	key 264
SELECT          (9)	key 265
L               (10)	key 266	(Values for the shoulders may be switched)
R               (11)	key 267
A               (12)	key 268
B               (13)	key 269
X               (14)	key 270
Y               (15)	key 271
VOLUP           (16)	key 272
VOLDOWN         (17)	key 273
STICK CLICK     (18)	key 274

** Save Config Settings **
---------------------
Save current Settings to Dosbox.conf
	This mapper will save the current cycles, frameskip, and font color selection's to
	currently used dosbox.conf. If the cycles or framekip are changed from the currently saved
	values then a '*' will appear in the upper left corner of the debug OSD. If you save
	the settings thought the mapper then the '*' will disappear, at least until you make 
	another change.
	Example:
		hand_saveconfig "key 256"

** Mouse Emulation **
---------------------
Mouse ON/OFF
	This option will enable and disable the mouse emulation. By default it is ON, but the mouse
	emulation will be off unless the gp2x_mouse_speed speed parameter below is set.
	Example:
		hand_g2mouse "key 256"

Mouse Cursor Movement:
	Add the parameter to the [sdl] section of the dosbox.conf. The parameter must be set to 0 or higher
	otherwise the mouse emulation will be disabled.
	The higher the number the slower the cursor will move. 0 is the fastest setting:
	Example:
		gp2x_mouse_speed = 0

Mouse Left/Right Clicks:
	Add the parameter to the mapper.txt file with the GP2X button desired for the action:
	Example:
		hand_leftclick "key 256" 
		hand_rightclick "key 257" 

Turn Touchscreen Clicks OFF:
	The feature will toggle ON and OFF when the GP2X mapped
	button is toggled. It does not effect GP2X button mouse clicks, only touchscreen clicks.
	Example:
		hand_noclick "key 256"
	
** Virtual Keyboard **
----------------------

The virtual keyboard will load a OSD surface that will overlay on top of the dosbox screen. This allows for sending of
common keys without needing a key mapped to a GP2X button. The parameter maps a GP2X button that turns the feature ON.
The menu consists of 2 parts a normal common menu and a special menu. The menus are switched by the last menu item.
Example:
	hand_g2virtkey "key 256"
	
	Controls:
	DPAD/Stick:	use to select character/key
	Start:		exit the menu
	B:		activate the selected character/key
	A:		quick-key for Enter/Return
	X:		quick-key for Backspace
	Y:		quick-key for Space
	Select:         change the color mode between normal font colors/selection font colors
	vol+		change the color of the font (depends on mode)
	vol-		change the color of the background of the font (depends on mode)
	
A mapping for each keyboard key needs to be included. All of these are in in VirtualKeyboardMapper.txt.
Just copy and add to your mapper.txt with your regular GP2X mappings. Do not change any of the
virtual keyboard mappings or they wont work.

Color of the virtual keyboard can be controlled  by these commands in the sdl section of the dosbox.conf.
Note: If you dont want to type these in the saveconfig mapper will save them in the dosbox.conf automatically.

fontcolor_front = 1
fontcolor_back = 2
fontcolor_frontsel = 3
fontcolor_backsel = 4

//  0 = white
//  1 = black
//  2 = red
//  3 = blue
//  4 = green
//  5 = yellow
//  6 = cyan
//  7 = pink
//  8 = orange
//  9 = dcyan
// 10 = grey
// 11 = ltgrey
// 12 = dkblue
// 13 = dkred
// 14 = dkgreen 
// 15 = transparent
	
	
** Zoom Feature Instructions **
-------------------------------
Add to the mapper.txt with the desired keys:
hand_g2zoom "key 266 mod1"
hand_g2nozoom "key 267 mod1"
hand_g2zleft "key 258 mod1"
hand_g2zright "key 262 mod1"
hand_g2zup "key 256 mod1"
hand_g2zdown "key 260 mod1"
hand_g2zmore "key 270 mod1"
hand_g2zless "key 271 mod1"
mod_1 "key 272"

The hotkey in this case is "Vol+", hold it and press the following keys
to zoom:

L - 1:1 zoom (no scaling)
R - full screen scaling (the way it works now)
Left,Right,Up,Down - move the current view
Y - more zoom
X - less zoom

The more zoom and less zoom allows for any size scaling, in increments
of 5%.

** On Screen Display Feature Instructions **
--------------------------------------------
Add to the mapper.txt with the desired keys:
hand_g2debug "key 265 mod1"

Will bind the "Vol+ + Select" to show/hide the OSD.

This requires a ttf font that needs to be named dbfont.ttf and be located in ./ and ../
(meaning you don't need a copy of the font on each game directory)

** GP2X Fullscreen Feature Instructions **
------------------------------------------
NO LONGER SUPPORTED - use the normal2x scalar

** Understanding the mapper.txt and what it all means for the GP2X **
---------------------------------------------------------------------
The mapper.txt is list of actions to be activated by a key press.
On the left is the action/dos key and on the right is the real keyboard key (or GP2X button's)

The mod item is best thought of a shift key option. Any key assigned to the mod can be used any 
of the other item maps to generate a muliple key combination. For example you will find 
most of the examples above use the stick click as the modifier, by doing this I use any other button
with my stick click to do an action. I can use the same mod template for my common actions like osd
and save the single presses for in game buttons.

A typical PC based dosbox build uses the mapper.txt to map real keyboard keys to dosbox virtual machine dos keyboard keys.
For dosbox on the GP2X we want to use the joystick buttons as virtual machine dos keyboard keys. The most simple way to do this
is to change each GP2X button to appear as a host machine keyboard SDL key event:

SDL GP2X Button event -> modified by code -> SDL Keyboard key event

By doing this the mapper.txt can be used to map the GP2X buttons to the desired dos key:

SDL Keyboard key event -> tranlates by mapper.txt -> internal dos key event

The GP2X buttons are modified to look like the numpad keys. These were chosen because the numberpad keys have a 
very high number representation. If anything lower was used it would conflict with the virtual keyboard.
The virtual keyboard generated a SDL keyboard event to be translated by the mapper.txt into a internal dos key.
That list of mapping's is provided in the virtual_keyboard_mapper.txt in the extras folder.


** Known Issues **
------------------
None

   .
** Installing **
-----------------
First the examples are assuming you put dosbox at /mnt/sd/dosbox. If you move to a different location
you will have to adjust the paths in the gpe script and the dosbox.conf.

Copy the dosbox subdirectory included in this archive to your SD card.  
Set up a separate configuration for each game you want to play.  That 
would consist of a dosbox.conf file, a mapper.txt file, and a 
gamename-here.gpe file.

The dosbox.conf holds your config settings for that game (have a look at the example one provided in the root)
The mapper.txt holds your keybindings - basically you can bind any press on the gp2x to a keyboard key.
The gamename-here.gpe holds the settings to boot up dosbox with that game's settings

Look in the sections above to set up any of the new features.

** Getting HELP **
-----------------
Check out the gp2x wiki located at : http://wiki.gp2x.org/wiki/DosBox
Also check out http://archive.gp2x.de/cgi-bin/cfiles.cgi?0,0,0,0,63
 This is a place on the archive server that everyone can add the configuration files needed for games.
 
Please post in the gp32x.com forums. I or someone else will be more than willing to help. Just do a little research
and post with full details. A little extra work is needed with dosbox, but to play your favorite old time
dos game it is worth it.
      
** THANKS **
-----------------
Many thanks to the Dosbox authors
Jim "bjimba" Russell for the SDL code
Boingball for readme and notes on his builds
DJwillis for support on the touchscreen
Hitnrun for the touchscreen code
M_HT major thanks for writing the ARM dynamic backend
Senor Quack for fixing up the SDL lib touchscreen code
BadAstronaut for F200 testing
M_HT for pointing out the obvious PORTING doc
Skutarth for the mapper converter and for testing
Eclipse for testing

Thanks to anyone else that effected this project and I left off the list. This really has become the effort of many
and wouldnt be where it is without everyone involved.

** The CHANGES **
-----------------
This version based on the released source package of 0.72 with the following changes:
1. Based off the work from 'Jim "bjimba" Russell'. He added the code to make the joystick send keyboard keys to dosbox.
2. Modified some setting based off of the PORTING document to save memory:
 a. in paging.h reduce the size of the TLB: #define TLB_SIZE (64*1024)               gain: ~15mb
 (I had added other memory savers, but they arnt needed)
3. Moved the SDL_ShowCursor(SDL_DISABLE) so that it always disables the cursor
4. Added touchscreen support for mouse emulation. Dosbox bases mouse movement off of relative position.
   This didnt give great results. So the the position is read direct from the SDL and a relative change is calculated
   and sent to the dosbox mouse handler function. A modification was also needed when the screen size is 320x200.
5. Profiled the code for optimization (possible 20% increase in speed, appears to be less than 10%) http://www.gp32x.com/board/index.php?showtopic=28490&st=15
6. Change some of the defaults settings.
7. Just for the heck of it I put the MMU hack back in. Doesnt make a noticeable  difference though
8. Added a zoom feature and OSD TTF feature
9. Added a dosbox.conf option to scale the image to fit the screen
10. Added mouse emulation support: Including mouse motion by DPAD/Stick, Left/Right/No clicks
11. Added a virtual keyboard menu. Able to send almost every key possible.
12. Touchscreen support for 320x200 was improved, the screen no longer needs to be scaled.
13. Added M_HT ARM dynarec backend (gives a small speed boost)
14. Added in Senor Quack's touchscreen changes to the SDL library. No more CPU loading when the screen is touched.
15. Fixed some things with the font and the config auto saver.
16. Added M_HT update arm thumb dynamic core changes

Note: Most changes made to the source were tagged with GP2X comment, just do a search and you will find everything.
      Most of the changes are in sdlmain.cpp.

** Building from Source **
--------------------------

1. Get a toolchain like open2x
2. Get the libs either prebuilt or build from source (you only need SDL a minimum)
3. Get the dosbox source (I upload my source to the archive)
4. ./configure (heres an example from a script I used)

#!/bin/sh

OPEN2X=/opt/open2x/gcc-4.1.1-glibc-2.3.6
HOST=arm-open2x-linux
TARGET=arm-open2x-linux

export OPEN2X
export HOST
export TARGET

PATH=$PATH:$OPEN2X/bin
export PATH

./configure --prefix=$OPEN2X --with-sdl-exec-prefix=$OPEN2X --host=$HOST --target=$TARGET --build=`uname -m` CPPFLAGS="-I$OPEN2X/arm-open2x-linux/include" CXXFLAGS="-O3 -fmerge-all-constants -ffast-math -funswitch-loops" LDFLAGS="-s -static -L$OPEN2X/arm-open2x-linux/lib" --enable-core-inline

5. make
6. You should have a binary.




