#
# SDLMESS 0.124
# by Olivier Galibert and R. Belmont
# Additional code by Sven Gothel, couriersud, and Vas Crabb.
#
# For Linux/Unix, Mac OS X (both PPC and Intel), FreeBSD, Win32, and OS/2 systems.
# Portable to anything remotely POSIX-y with SDL 1.2.11 or higher available.
#
# Note: the Win32 target is not intended to compete with baseline MESS - it's 
#       simply a demonstration that SDLMESS works well with that OS.
#

Changes from 0.124
==================
1) Up to date with baseline 0.124 and SDLMAME 0.124 (RB)


WARNING: build instructions are now different from prior to 0.121u3!
For PowerPC Macs and the PS3, you now must set "BIGENDIAN=1" instead of picking a specific CPU.

NOTE: The makefile should be fully SMP safe, so use make -j3 for dual-core 
and -j5 for quad-core to build MESS at speeds never before achieved.

Known problems: 

* Fedora 8 ships with a defective setup for SDL audio.  This causes no sound in SDLMAME
  and a lockup on exit.  To work around this, update your SDL and SDL-devel packages to 
  version 1.2.12-5.fc8 or later ("sudo yum update SDL SDL-devel" should do the trick).
  
  If you are unable to access/download Fedora updates, set the SDL_AUDIODRIVER environment 
  variable to esd, like this:

  bash (default): export SDL_AUDIODRIVER esd
  csh/tcsh: setenv SDL_AUDIODRIVER esd

* SDL 1.2.12 on Mac OS X appears to have a crash problem associated with keyboard input.
  This has been fixed for 1.2.13 which is now available, so upgrade and this will go away.

* Do not use -mt (multithreading) on Mac OS X at this time.  This affects only
  offloading the final blit - you will still get the full benefit of multiple
  processors automatically on the heavier/3D games.

* MAME's core has some big-endian problems still - this causes some games to 
  not work or work improperly on systems with a PowerPC CPU, including older 
  Macs and the Playstation 3.  In the case of Neo-Geo games, when the real 
  parent set doesn't work often some clone/bootleg sets will.  For instance 
  kof2003 is broken right now, but the 4 bootleg/clone sets all run fine.  
  Ironically MAME's PowerPC core is not big-endian safe so PPC-based arcade 
  games won't emulate properly on systems with a PPC CPU.

* Neither scale2x nor -prescale are supported for games with video overlays
  (currently  Dragon's Lair and the American Laser Games games, none of which 
  are actually playable yet).  Use -video soft to see the alg.c games run as 
  they do on baseline.  (This will of course be fixed if/when video is actually 
  added).


Recommended benchmark switches: -noartwork -nosound -video none -nothrottle -ftr 5000 -window
But feel free to customize.


Requirements
============
GCC: 3.4.x, 4.0.x, or 4.1.x (3.4.5 and 4.1.2 are recomended).  Older or newer 
versions may expose you to compile problems.
SDL: 1.2.10 or later on Unix and Mac, 1.2.11 or later on Win32.


Build instructions
==================

Linux: make sure you have SDL and it's development packages installed via 
apt-get, yum, emerge, or whatever your distro of choice uses. On Fedora 4 or 
later, 'yum install SDL SDL-devel' will get you going assuming you already 
have GCC. If you already can compile XMAME/XMESS with the SDL target you're 
good to go. Just edit makefile.sdl, change the options as necessary, and 
type 'make -f makefile.sdl'.

In most cases on Linux you'll want to comment out BUILD_EXPAT and BUILD_ZLIB 
since most systems have them already present and you'll save some time and 
memory using the system's version (plus if security problems arise your 
distro's normal update will protect SDLMESS without having to upgrade SDLMESS).

For native 64-bit x86-64, you should build with PTR64=1 (or uncomment it 
in the makefile).

For Linux/PPC (including the PlayStation 3) you should build with 
BIGENDIAN=1 (or uncomment it in the makefile).

NOTE: you will need OpenGL headers and libraries as well.  If you're 
running either ATI or NVIDIA's binary-only drivers you've definitely got them.
Otherwise you may need to install the "MesaGL" and "MesaGL-devel" packages.  

NOTE: if you do not have hardware accelerated OpenGL you should not try to 
enable it, it'll just go horribly slow.

--

Mac OS X: you'll need Xcode 2.3 or later (a free download from 
developer.apple.com) and SDL 1.2.13. Get SDL from www.libsdl.org, click the 
"SDL 1.2" download link in the sidebar, then scroll down to "Mac OS X" under
"Runtime Libraries".  Download the "SDL-1.2.13.dmg" disk image and open it.  
Click 'Macintosh HD' or whatever your Mac's hard disk is named in the left 
pane of a Finder window, then open the Library folder and drag the 
SDL.framework folder from the SDL disk image into the 'Frameworks' folder. 

Next unzip the SDLMAME source in your home directory.

For Intel Macs, type make -f makefile.sdl TARGETOS=macosx 
For PowerPC Macs, type make -f makefile.sdl TARGETOS=macosx BIGENDIAN=1

NOTE: if you experience issues with OpenGL mode make sure your OS X is up to 
date first, especially for Tiger (10.4.x) on Intel Macs.

--

Win32: First, download SDL 1.2.13.  Go to www.libsdl.org and click "SDL 1.2" 
under "Downloads".  Scroll down to "Development libraries" and open 
"SDL-devel-1.2.13-mingw32.tar.gz".  Assuming you have WinZip ora compatible 
archiver installed it should open automatically.  Decompress it into C:\, where 
it will create the "SDL-1.2.13" folder.  Open that folder.  Drag the "bin" and 
"lib" folders into your MinGW installation (note: it must be a mame.net style 
install, raw MinGW will not work).  Finally, create a new folder "SDL" inside
"include" in your MinGW install (e.g. MinGW\include\SDL) and copy the contents 
of SDL-1.2.13\include into that folder.

Now, Edit makefile.sdl with e.g. "edit makefile.sdl" or Notepad or whatever.  Change 
the TARGETOS to "win32" and change the CPU type to whatever you need.  The 
other defaults should be fine for you.  Type  'mingw32-make -f makefile.sdl' 
to build SDLMESS.  Unlike normal MESS, you'll need the SDL.dll from the 
SDL package in order to run it, so don't try moving it to another machine 
without that file accompanying it.

NOTE: MinGW appears to already come with sufficient OpenGL headers and 
libraries to build.  If problems occur, make sure your video card drivers are 
up to date.

--

Other: SDLMESS should work with very little effort on other SDL targets, 
especially Unix and Unix-like ones.  Start with the Linux target and 
modify as necessary.  For non-Intel systems, turn off the X86_*_DRCs.  
For big-endian systems, don't -DLSB_FIRST.  If you get SDLMESS 
running on other platforms, let us know.

-------------------------------------

Run-time options:

Most of these are the same as for the Win32 version of MESS and so familiarity with that program will
pay off here.  The video options behave somewhat differently, however, so they get special coverage.

Please see docs/windows.txt for the baseline windows options - just ignore the stuff about DirectX :-)
If you're not sure about what Windows options SDLMESS supports, run it with the -showusage switch.

-natural / -nat: enables "natural keyboard" support for computers.  By default, SDLMESS tries to map your
PC keyboard to match the layout of the emulated computer's.  This means that e.g. Shift-2 on a C64 will
give " rather than the @ you expect.  In natural keyboard mode that mechanism is bypassed and your keys
will generate the symbols printed on them.

-uimodekey / -umk: when emulating a computer MESS automatically ignores the standard MAME keys in favor
of passing them through to the emulation.  This however leaves you with no way to exit since the emulated
computer gets the Esc key then.  MESS's solution is to map one special key which toggles if the MAME keys
are enabled or passed through to the emulated computer.  This is normally Scroll Lock on PC builds and 
Help on Macs, but you can use this option to change it to something else in case you really need Scroll 
Lock to work on the emulated system or something.

-keymap: set to 1 to use a keymap file.  These are used to work around non-US keyboards due to limitations
 in SDL.  Use in conjunction with -keymap_file.

-keymap_file: specify a keymap file to use.  Must have -keymap 1 for this to work.  Supplied keymaps in the
 keymaps/ directory are:

 km-ch.txt - Swiss keyboard on Linux
 km-de.txt - German keyboard on Linux
 km-fr.txt - French keyboard on Linux
 km-fr-OSX.txt - French keyboard on Mac OS X

If you have a non-US keyboard which is not one of those types, please refer to this thread for information on
how to make your own:

http://www.bannister.org/forums/ubbthreads.php?ubb=showflat&Number=32956&page=1&fpart=2

Pay close attention to the posts by "couriersud".  We hope to translate this into normal text documentation
at some point as well.

-oslog: Turns on logging and shows it in the console/terminal window you started SDLMESS from.  For technical
 users / developers only.

-mt / -multithreading: Enables limited support for multiple CPUs.  This is not a magic speedup and may cause
 instability.  Do not use at all on Mac OS X or you *will* crash!

-sdlvideofps: Shows performance data on SDLMESS's video code.

-video: "soft" uses software rendering, which is slower but more compatible.  "opengl" uses OpenGL and your
 graphics accelerator to speed up many aspects of drawing MESS including compositing artwork, overlays, and
 bezels, as well as stretching the image to fit your screen.  "opengl16" also uses OpenGL, but with a different
 texture format that some graphics cards/chips may prefer.  "none" does no drawing and is intended for
 CPU benchmarking.

If your video card doesn't support OpenGL you can still get hardware scaling with -yuvmode:

-yuvmode: "none" (default) no yuv overlay, current "SOFT" rendering, "yuy2": yuy2 overlay, "yuy2x2": yuy2 
overlay using x2 prescaling, "yv12": yv12 overlay, "yv12x2": yv12 overlay using x2 prescaling.

When this is enabled, you'll see a status printout "YUV Acceleration:" - if it's "Hardware" you're getting
hardware scaling and can resize the window with no worries about slowdown.

Within SDLMESS you can switch between the modes using

CTRL-F8: previous yuv mode
CTRL-F9: next yuv mode

-window: Enable window mode rather than fullscreen.  This is a fully-featured window mode where the 
 window resizes as necessary to track what the game does, and you can also resize it in the usual way.

-keepaspect / -ka: Forces the correct aspect ratio.  This means when you're resizing the window in windowed
 mode the actual game image will resize in discrete steps to maintain the proper shape of the game graphics.
 If you turn this off you can resize the window to anything you like and get funny squishing and stretching.
 The same applies for full-screen.

-numscreens: For future (SDL 1.3) use.  Keep set to "1" unless you like crashing.

-extra_layout / -layout: Specify a layout file to use instead of any built-in ones for this game.

-switchres: Affects full screen mode only.  Chooses if SDLMESS can try to change the screen resolution
 (color depth is normally left alone) when in full-screen mode.  If it's off, you always get your desktop
 resolution in full-screen mode (which can be useful for LCDs).

-fullstretch / -fs: Allows stretching in non-integer steps.  Video purists should stay far, far away from this
 option, while everyone else will be happy to know that it lets you fill the screen properly in full-screen 
 mode.

-screen0 / -screen: For future (SDL 1.3) use.  Keep on "auto" for now.

-aspect0 / -screen_aspect: Select the aspect ratio of your monitor, in colon form (e.g. "4:3" or "16:9").
 This affects full-screen mode only, so if you have a widescreen monitor you should set it's proper ratio here.
 Autodetect will only work if you use the monitor's native resolution, which can get extremely slow in 
 "soft" mode.  It's normally not a problem when using OpenGL.

-resolution0 / -resolution / -r: Select the resolution to use in full-screen mode.  "-switchres" must be
 enabled for this to work.

-view0 / -view: Select the named view to use.

OpenGL switches (no effect for -video soft):

-gl_notexturerect (set to 0 if you experience corruption in OpenGL mode.  Will reduce performance)

-gl_forcepow2texture  (set to 1 if you experience corruption in OpenGL mode.  Will reduce performance)

-gl_vbo (set to 1 if you have a newer video card for a performance increase, turn off if corruption occurs)

-gl_pbo (set to 1 if you have a newer video card for a performance increase, turn off if corruption occurs)

-gl_glsl (set to 1 to offload some more work to your video card via pixel shaders - requires OpenGL 2.0)

-gl_glsl_filter (set to 0 for no filter, 1 for bilinear, and 2 for Gaussian blur - requires gl_glsl set to 1)

-gl_glsl_vid_attr (set to 1 to have the video card handle brightness/contrast/gamma - can be a good 
 performance boost on some games)
