Mac Emulator Shell

v2.1 (September 16th, 2006)

http://www.bannister.org/software/

About

The enclosed emulator uses the Macintosh Emulator Port Shell by

Richard Bannister. This has a common feature set between all
supported emulators, which this document attempts to cover briefly.

System Requirements

Emulators using this shell require Mac OS X 10.4 or later.

For good performance, a video card with at least 32MB of VRAM is

recommended. As a general rule of thumb, if your video card uses AGP
and supports Quartz Extreme, then it should be enough to make the
most of most features of this shell.

ROMs/Games/etc

All these emulators require ROM images or games in order to do

anything useful. Transferring software from old platforms typically
requires special hardware to accomplish. Documentation on how this
is done is widely available on the Internet.

Distribution of such software on the Internet counts as software piracy

unless the copyright owners have given their express permission for
this to take place. Amstrad, for example, has given permission for their
entire back catalog to be used in emulation, and they deserve praise
for their enlightened attitude. Once again, an Internet search will point
you to what you need.

A good place to start is the site http://www.pdroms.de/.

Do not under any circumstances ask me to send you game files, and
do not ask me for further information beyond the above. The act of
requesting such information officially revokes any license you have
to use my software.
Additional Options

A number of extra features may be added to this emulator by way of

the Emulator Enhancer plugin. These include:

- Aspect ratio correction.

- Bilinear filtering.
- Custom icon generation.
- Full screen mode support
- Screen curvature emulation
- Support for USB game pads.
- Support for network play (certain emulators).
- VBL synchronized video

The plugin may be downloaded from

http://www.bannister.org/software/.

Main Window

The main window of each supported emulator can be resized to any

size you like. The zoom box will zoom to the next larger size while
preserving the default aspect ratio. If you want to play in another size,
simply drag the grow box in the bottom right hand corner of the
window. (It's not visible - but it is there).

You can adjust the aspect ratio and sizing by holding down the shift
and option keys while using the grow box.

Preferences

Video Tab

- Frame rate specifies the desired frame rate of the emulator. If your
Mac is not fast enough to support the specified frame rate, then the
emulator will not run at full speed. This option can normally be left on
Automatic for best results.
- Display Frame Rate shows the current frame rate on the top right
hand corner of the emulated display.

- Software Effects allow various different transformations to be

applied to the image before the video is drawn. The effect size
indicates the size of the source image before the final video copy is
done. If this is bigger than the window size, the image will be scaled
down with OpenGL; if it is smaller, then it will be scaled up. It is
important to realise that larger effect sizes have a significant
performance penalty, especially on slower video cards. A double size
effect for example needs to push four times as much data to the video
card every frame as a single size one, and that doesn't include the
overhead required to apply the effect first. If you have a G4, G5, or
Intel Mac, then try out Super2xSAI (at 2x) or HQ3X (at 3x) for
exceptional quality smoothing.

Interface Tab

- Speed specifies the desired emulated speed. This will only be

achieved if your Mac is fast enough; specifying 500 fps won't do any
good if you're on an original iMac, for example.

- Prioritize speed over smoothness can provide a slightly better frame

rate on slower Mac models at the expense of a slight unevenness in
timing. If you've got a fast Mac, you can probably turn this off.

- The pause emulation options and sound emulation options (if

present) do exactly what they say.

- Brushed metal interface options affect the appearance of the main

emulator window and about box.

Emulator Tab

If the specific emulator you are using has any special options, they can
be found here.

Joysticks Tab

The joysticks tab allows you to map emulated joysticks to specific

keys on the keyboard.

Developers

It was my intention to make a SDK of this shell available for others to

use with the v1.5 release. Due to time constraints, this has been
postponed indefinitely.

However, the Blitter module used by this shell is now available under
the LGPL license. Though it is not available to download at the time of
writing it is available on request; drop me an e-mail if you want a copy.
The code builds as a Universal Binary in the latest release of Xcode.

The Blitter module is separate from the rest of this program and can
be found inside the application package.

Thanks

Special thanks to all those who have tested this software during its
development cycle, and to all those who create emulation technology
for our enjoyment.

Version History

v2.1 - September 16th, 2006

- Major rewrite to internal file handling code. This brings support for
long file names and non-ASCII character sets. The most visible aspect
of this change is that Japanese file names now appear correctly in the
emulator. (You may need to rename some existing battery RAM
files/saved states so that this update can see them correctly.)

- Fixed several endian bugs; of particular note, screenshots and audio

recordings now work correctly on Intel Macs.

- File extensions are now included by default when saving screenshots

or audio recordings.
- Worked around issue preventing keyboard from working in full screen
mode in Arnold and Frodo.

- Resolved a number of situations where keyboard input would be

registered even though the emulator window was not active.

v2.0 - April 15th, 2006

- Ported to Xcode and recompiled as Universal Binary.

- Interleaved blitters now work properly on multiprocessor machines.

- Fixed an issue where keyboard configuration could occasionally get

confused during an emulator upgrade. In this situation, the keys are
now reset to their defaults.

- Internal code now uses FSRef instead of FSSpec.

- Placard drawing ("Emulation Reset" etc) now uses CoreGraphics

instead of QuickDraw.

- Fixed an issue where Close menu item was not disabled when no
ROM was open in some emulators.

- Removed some obsolete code that was slowing down overall

performance.

- Fixed several memory leaks.

v1.6.5 - November 13th, 2005

- Addressed an issue with the sound buffering code that had caused
poor quality sound output in BSNES. This may have a positive effect on
other emulators too.

v1.6.0 - October 6th, 2004

- Addressed an issue where the menu bar would not appear properly
on program launch in certain situations.

- Configure Keyboard button is no longer present in emulators that do

not support it.

- Some internal changes to allow compilation in Xcode.

- Added statistics gathering (Time Played, Files Opened) to the code.

There is no way to view these yet, but this will come in future.

v1.5.3 - December 11th, 2004

- Fixed bug causing unreasonably high CPU usage when in background

when the "Run as fast as possible" option was set. Thanks to Ty
Wangsness for the report.

- Fixed assertion failure, ce_file.c line 202, when using the "Open With"
contextual menu in the Finder on Horizon. Thanks to Eric Crouch for
the report.

- Fixed issue where Turbo key in console emulators did not work
correctly when "Sync to Monitor Refresh" was on. Thanks to Revned
for the report.

v1.5.2 - September 30th, 2004

- Removed "Cancel" button from Preferences. It hasn't worked for

several releases anyway.

- Quick Screenshot now adds a three digit number to file names.

Useful if you want to take multiple shots of one game.

- Added the ability to record audio. Note that this option requires
emulator updates.

v1.5.1 - July 9th, 2004

- Fixed small memory leak in windowing code.

- Added the ability to modify the frame rate colour.

v1.5 - June 19th, 2004

- Some reworking under the hood to make things work on Mach-O.

- Saved states/etc now get put in /Users/*/Library/Application

Support/Bannister/Emulator Name/*.

- Quick Screenshot now saves files on the desktop.

- Added the ability to pause emulation when the active user is

switched.

- Improved support for Macs with more than one monitor.

- Separated Blitter module (see "Developer" above) and added some

new Altivec blitter code for the most common effects. In most cases
this is significantly faster on G4/G5 machines. (The old code is still
available too for G3 users).

- Further performance enhancements in OpenGL code.

- Revised Preferences handling to use official Apple API and .plist file.

- Large numbers of bug fixes.

v1.4.2 - February 5th, 2004

- Sped up code used to draw frame rate.

- Improved error handling in the sound code.

v1.4.1 - December 25th, 2003

 - Implemented major optimization to the OpenGL code. People with
supported video cards may see as much as a 100% performance
improvement.

- Fixed bug in HQX blitters introduced in v1.3.1, which caused the

bottom row of video to be corrupted in certain situations.

- Fixed issue preventing saved states getting the correct file type.

- Updated to ZLIB v1.2.1. (Previous shell did not include ZLIB, and
emulators were using assorted versions).

v1.3.1 - December 1st, 2003

- Fixed possible memory corruption with emulators that change their

video size during execution. (Genesis Plus, TGEmu, ...)

- More optimizations to the hqx blitters, improving the worst case

performance significantly.

- Addressed an issue where keys would continue to work when certain

emulators were in the background.

- Added "quick screenshot" function (requires emulator updates).

- About box now observes brushed metal preference (which is now on

by default).

- Some optimizations to the main program loop for improved

performance. There is still more to do, though.

- Major bug fixed in the frameskipping code; people on slower Macs

should see a substantial improvement in frame rate. (Be sure to leave
the frame skipper in Automatic mode for best results).

v1.2.3 - November 4th, 2003

- Did some serious optimization to hq2x, hq3x, and hq4x, leaving them
up to 300% faster than previous versions. (The source code to my
optimized version has been sent back to Maxim Stepin, the
hq2x/hq3x/hq4x developer).

- Fixed a situation where placard displays ("Emulation Reset", etc)

failed to disappear correctly.

v1.2.2 - October 30th, 2003

- Added support for frame rate changing at run time (required by

Generator and Rainbow).

v1.2.1 - October 12th, 2003

- Moved default Quick Freeze/Defrost keys to F7/F8 to avoid conflict

with Expose.

- Placard displays now work again ("Emulation Reset", "Quick Freeze",

etc).

v1.2 - September 30th, 2003

- Added some hooks needed by fMSX.

- Added hq2x and hq4x Blitter modes (the latter of which *does* need
a dual 2.0 G5 for full speed).

- Added 3x Simple Smoothing mode (pretty fast).

- Fixed an issue preventing windows being bigger than 5x actual size.

- Fixed a bug in Preferences handling that could make options not

work when the Default button was pressed.

v1.1 - September 3rd, 2003

 - Added support for non-power-of-two textures. The cards that need
this the most (RAGE 128 and earlier) do not support this extension.
However, everyone else should see a performance improvement.

- Tweaked window resizing to match QuickTime. Aspect ratio is

preserved by default; hold down shift key to go to strange sizes, or hold
down option key to stick to regular multiples.

- Adjusted window alignment code to limit to four-pixel boundaries

instead of eight.

- Increased number of items in Open Recent menu to ten, and added

"Clear Menu" option.

- Fixed issue where battery RAM and freeze states did not work
correctly when Emulator Enhancer was installed.

- Added support for overriding the generic keyboard handling (needed

for computer emulators such as MO5 and Oric).

v1.0 - August 7th, 2003

- Initial Release