===========================================
   MAME4ALL Dingux 1.2 (November 11, 2009)
    For the A320 Dingoo running Linux
               by Slaanesh 
          http://www.slaanesh.net/
        Contact me at www.gp32x.com
===========================================


1. INTRODUCTION
---------------

MAME4ALL Dingux is a port of MAME 0.37b5 emulator (originally by Nicola Salmoria) for the A320 Dingoo running Linux. MAME4ALL is also available for the GP2X, Wiz, PSP and GP32.  Please refer to the MAME license at the end of this document.

MAME4ALL Dingux currently emulates most arcade games supported by original MAME 0.37b5 plus some additional games from newer MAME versions. Some larger games currently do not work due to lack of system RAM.

Official web page for news, additional information and donations:

http://users.bigpond.net.au/mame/dingoo/


2. CONTROLS
-----------

Standard in-game MAME controls:

- D-Pad: UP, DOWN, LEFT and RIGHT.
- Buttons A,B,X,Y,L,R: MAME buttons 1,2,3,4,5,6.
- Button SELECT+START: Insert credit.
- Button START: Start game.


Extended controls in game (to access menus and options)
All use the SELECT button + an additional button.
This is analagous to pressing "SHIFT" and another key on a regular keyboard.

- Buttons SELECT+L: Show profiler.
- Buttons SELECT+R: Show FPS.     
- Buttons SELECT+A: Enter/Exit MAME menu.
- Buttons SELECT+Y: Enter/Exit MAME menu (Same as above, alternative).
- Buttons SELECT+B: Enter/Exit Volume menu.
- Buttons SELECT+X: Pause.
- Buttons SELECT+L+R: Exit (to frontend menu).


The "MAME menu" (see above) can be used to:

- Redefine DEFAULT keys for all games.
- Redefine keys for the current game.
- Display game information.
- Set Auto-fire options.
- Enable cheats.

Controller Notes:

- All keys can be redefined, including the "shifted" SELECT keys.
  In some cases this is essential. ie. Robotron.
- To type OK when MAME requires it, press LEFT and then RIGHT.


3. GAME SELECTOR
--------------------
MAME can be run directly from the 'mame' executable by using command line options.  However, a far easier way of running MAME is using the 'mamefront' Game Selector. This will launch 'mame' with the options chosen.

The Game Selector will automatically save specific options for each game.

The Game Selector will search for MAME ROMs found in the ./roms directory. Games found will be displayed in the game list.

- Use UP and DOWN to select a game.
- Use LEFT and RIGHT to page up and page down.
- Press A to select the game to play.
- Press SELECT+L+R to exit.

After selecting a game, configuration options are available:

- Use UP and DOWN to select the option you want to change.
- Use LEFT and RIGHT to change the option.
- Press A to start the game (and save the configured options).
- Press B to go back to the game list.

Configuration options:

-- Dingoo Clock --
300 - 420 MHz options are available. 336 MHz is the standard value. Use greater values at your own risk!.

-- Video Depth --
Sets MAME's internal video depth (NOT the Dingoo's video depth).
8-bit is generally faster though some games require 16-bit.
Some games may be faster in 16-bit mode - it's dependant on the game driver!
Auto: The emulator uses the most suitable video depth.
8 bit: MAME uses 8 bit color (DEFAULT).
16 bit: MAME uses 16 bit color.

-- Video Scale/Aspect --
The video aspect is configured with the following combination of options:

Normal:
Nominal video resolution (320x240). Games with a resolution less than this have a black border. Games with a resolution higher are cropped.

Scale Half Size:
Useful for high resolution games like Rampage and Tapper, etc. 8-bit video mode is quickest as extra pixels are just truncated. 16-bit mode does pixel mixing resulting in a nicer, but slightly slower display. Should still be quick enough for most games.

Scale Horizontal:
Useful for games like R-Type and Final Fight, etc. Other smaller resolution games will stretch out to fill the screen. Take from MAME4ALL Wiz version (code originally from Notaz & Franxis).

Scale Best:
This is a generic rescale that can resize any screen to fit the Dingoo's native 320x200 resolution. It produces the best quality scaled display as pixels are merged both horizontally and vertically. The downside is that it may be slow.

Scale Fast:
his is a generic rescale that can resize any screen to fit the Dingoo's native 320x200 resolution. It produces a good scaled display as pixels are merged horizontally. Speed should be somewhat quicker than "Scale Best".

Rotate:
The display is rotated from landscape to portrait orientation. All the above scale options are present for screen rotation.

-- Video Sync --
Normal: Single buffer and dirty buffer is used (DEFAULT).
VSync: VSync activated (Unlikely to be ever implemented due to lack of hardware support).
DblBuf: Double buffer without dirty buffer (NOT IMPLEMENTED YET).
OFF: No video synchronization, use manual frameskip.

-- Brightness --
The A320's LCD screen brightness can be adjusted in increments of 10% from 0%-100%. 

-- Sound --
The sound options are the following ones:
ON: The sound is activated. 8, 16, 24, 32 KHz sound mixing rates are available in both mono and stereo, (16000hz mono DEFAULT).
OFF: The sound is disabled. This can vastly improve the speed of the game.
Fast sound: Improve performance at the cost of sound quality.

-- CPU Clock --
The clock of the CPUs can be adjusted from 50% to 200%. The nominal value is 100% (DEFAULT) and the CPU is emulated accurately.
The clock can be safely underclocked to about 80% to gain performance in almost all games (be careful because some games could not run correctly). Use lower values to get more performance but probably several more games would not run correctly. Also the clock can be overclocked up to 200%.

-- Audio Clock --
The clock of the audio CPUs can also be adjusted from 50% to 200%. The nominal value is 100% (DEFAULT). See "CPU Clock" above.

-- CPU Cores --
(NOT IMPLEMENTED YET)

-- Volume --
Set the starting volume of the game. Most games start very loudly! Use this to save your ears.
Max: Full volume (DEFAULT).
Medium: Volume reduced a bit.
Low: Volume reduced more.
Quiet: Most likely barely audible but depends on the game.

-- Cheats --
ON: The cheats are enabled. To access in game press SELECT+START and enter the "Cheats" menu.
OFF: The cheats are disabled.
Note: The high scores are not saved if cheats are enabled!!!.

-- Auto-Fire --
To access the auto-fire configuration, during game press SELECT+START and enter the "Auto-Fire" menu.


4. INSTALLATION
---------------

MAME4ALL for Dingux can be installed in any directory under the "local" directory of your SD card.

A typical installation may go in /local/mame4all or /local/games/mame4all in the VFAT partition of your SD card.

The following files and directories may exist in the mame4all directory.
Optional entries are noted with [*].

mame.dge        -> Frontend game selector.
mame.png        -> [*]Frontend game icon.
mame            -> MAME emulator
cheat.dat       -> [*] Cheats definition file
hiscore.dat     -> [*] High Scores definition file
artwork/        -> [*] Artwork directory
cfg/            -> MAME configuration files directory
frontend/       -> Frontend configuration files
hi/             -> [*] High Scores directory
inp/            -> [*] Game recordings directory
memcard/        -> [*] Memory card files directory
nvram/          -> NVRAM files directory
roms/           -> ROMs directory
samples/        -> [*] Samples directory
skins/          -> [*] Frontend skins directory
skins/previous  -> [*] Previous versions of frontend skins directory
snap/           -> [*] Screen snapshots directory
sta/            -> [*] Save states directory

To auto launch mame4all (ie. not using an application launcher) place the "main" script in the following location of your SD card:

miniSD:/local/sbin/main -> [*] Script to auto-run mamefront


5. SUPPORTED GAMES
------------------

The original version of MAME 0.37b5 supported 2260 romsets. For more details, see "gamelist.txt" file.
Games must be copied into the <installdir>/roms/ folder on the SD card.
For example if mamefront and mame are installed in /mnt/sd/mame4all then the roms dir would be /mnt/sd/mame4all/roms

Neo Geo games are currently not included. Use FBA320 instead for these.


6. ROM NAMES
------------

Folder names or ZIP file names are listed on "gamelist.txt" file.
Romsets have to be MAME 0.37b5 ones (July 2000).
Additionaly there are additional romsets from newer MAME versions.

Please use "clrmame.dat" file to convert romsets from other MAME versions to the ones used by this version for Dingoo, using ClrMAME Pro utility, available in next webpage:

http://mamedev.emulab.it/clrmamepro/

NOTE: File and directory names in Linux are case-sensitive. Put all file and directory names using low case!.

!!!! THE MOST COMMON PROBLEM FOR NOT GETTING A SUPPORTED GAME TO RUN IS INCOMPATIBLE ROMS. !!!!


7. SOUND SAMPLES
----------------

The sound samples are used to get complete sound in some games.
They are placed into the 'samples' directory compressed into ZIP files.
The directory and the ZIP files are named using low case!.

The sound samples collection can be downloaded in the following link:
http://archive.gp2x.de/cgi-bin/cfiles.cgi?0,0,0,0,5,2511

You can also use "clrmame.dat" file with ClrMAME Pro utility to get the samples pack.


8. ARTWORK
----------

Artwork is used to improve the visualization for some games. Download it here:
http://archive.gp2x.de/cgi-bin/cfiles.cgi?0,0,0,0,5,2512


9. ORIGINAL CREDITS
-------------------

- MAME 0.37b5 original version by Nicola Salmoria and the MAME Team (http://www.mame.net).

- Z80 emulator Copyright (c) 1998 Juergen Buchmueller, all rights reserved.
- M6502 emulator Copyright (c) 1998 Juergen Buchmueller, all rights reserved.
- Hu6280 Copyright (c) 1999 Bryan McPhail, mish@tendril.force9.net
- I86 emulator by David Hedley, modified by Fabrice Frances (frances@ensica.fr)
- M6809 emulator by John Butler, based on L.C. Benschop's 6809 Simulator V09.
- M6808 based on L.C. Benschop's 6809 Simulator V09.
- M68000 emulator Copyright 1999 Karl Stenerud.  All rights reserved.
- 80x86 M68000 emulator Copyright 1998, Mike Coates, Darren Olafson.
- 8039 emulator by Mirko Buffoni, based on 8048 emulator by Dan Boris.
- T-11 emulator Copyright (C) Aaron Giles 1998
- TMS34010 emulator by Alex Pasadyn and Zsolt Vasvari.
- TMS9900 emulator by Andy Jones, based on original code by Ton Brouwer.
- Cinematronics CPU emulator by Jeff Mitchell, Zonn Moore, Neil Bradley.
- Atari AVG/DVG emulation based on VECSIM by Hedley Rainnie, Eric Smith and Al Kossow.
- TMS5220 emulator by Frank Palazzolo.
- AY-3-8910 emulation based on various code snippets by Ville Hallik, Michael Cuddy, Tatsuyuki Satoh, Fabrice Frances, Nicola Salmoria.
- YM-2203, YM-2151, YM3812 emulation by Tatsuyuki Satoh.
- POKEY emulator by Ron Fries (rfries@aol.com). Many thanks to Eric Smith, Hedley Rainnie and Sean Trowbridge.
- NES sound hardware info by Jeremy Chadwick and Hedley Rainne.
- YM2610 emulation by Hiromitsu Shioya.


10. PORT CREDITS
----------------

- MAME4ALL Dingux by Slaanesh based on source code from the GP2X port of MAME4ALL.
- The original MAME4ALL is based on MAME 0.37b5.


11. DEVELOPMENT
---------------
November 30, 2009:
- Version 1.2. Bug fixes. Speed increase. Brightness control.

July 23, 2009:
- Version 1.1. Video Scalers. Volume Control. Pole Position fix.

July 11, 2009:
- Version 1.0. First version.


Developed with:
- Cygwin.
- Ingenic mipsel toolchain (originally with mipsel-linux-g++ v3.3.1, subsequently with(mipsel-linux-g++ v4.1).
- Dingoo minimal library based on GP2X SDK v0.C by Rlyeh (http://www.retrodev.info/).
- GpBinConv by Aquafish (www.multimania.com/illusionstudio/aquafish/).
- Paint Shop Pro.


12. TO BE IMPROVED
------------------

In order of priority:

- Improve support for existing games.
- Add support for larger games.
- Use faster CPU cores for M68000 and possibly Z80.
- Other speed optimizations.


13. THANKS TO
-------------

- Franxis: Originally porting MAME to GP32, GP2X and Wiz (http://www.talfi.net/gp32_franxis/).
- Booboo: For the amazing "Dingux" Linux for Dingoo (http://www.dingux.com/).
- A600: For new kernels and discussions.
- Danibat: For the green menu skin.



14. SKINS
---------

The frontend graphic skin used in the emulator can be changed by adding two new files:
skins/dingoosplash.bmp   -> Game selector intro screen.
skins/dingoomenu.bmp     -> Game selector background screen.

Bitmaps MUST be 320x240 pixels x 256 colors (8 bit).
The resulting file should be exactly 77878 bytes in size. If it is not, then
it's not in the right format. Paint Shop Pro saves BMPs in the correct format.

Previous versions of splash screens are included in the skins/previous directory.


15. MAME LICENSE
----------------

http://www.mame.net
http://www.mamedev.com

Copyright  1997-2009, Nicola Salmoria and the MAME team. All rights reserved. 

Redistribution and use of this code or any derivative works are permitted provided that the following conditions are met: 

* Redistributions may not be sold, nor may they be used in a commercial product or activity. 

* Redistributions that are modified from the original source must include the complete source code, including the source code for all components used by a binary built from the modified sources. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.  
* Redistributions must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
