<HTML>
<HEAD>
<TITLE>ColEm Documentation</TITLE>
</HEAD>
<BODY BGCOLOR=#FFFFFF LINK=#006000 VLINK=#006000>
<CENTER>
<H1><FONT COLOR=#FF0000>ColEm<BR>version 2.5</FONT></H1>
<H3>by <A HREF="http://fms.komkon.org/">Marat Fayzullin</A></H3>
</CENTER>>
<H1>Contents</H1>
<UL>
<LI><A HREF="#LABB">New in This Version</A>
<LI><A HREF="#LABC">Introduction</A>
<LI><A HREF="#LABH">Buttons</A>
<LI><A HREF="#LABI">Command Line Options</A>
<LI><A HREF="#LABJ">Frequently Asked Questions</A>
<LI><A HREF="#LABK">History</A>
<LI><A HREF="#LABI">Thanks to...</A>
</UL>
<A NAME="LABB">
<H1>New in This Version</H1>
</A>
<UL>
<LI>Yet again ported ColEm to Unix using the new EMULib
framework. The new <B>ColEm-Unix</B> has been tested to compile
and run on Ubuntu Linux but should work on any other Unix.
ColEm-Unix source code is included with the core source code
distribution.
<LI>Ported ColEm to Maemo OS2008 used in N800 and N810 internet tablets
from Nokia. <B>ColEm-Maemo</B> has been specifically optimized for
the tablets using ARM assembler. It will simulate joypad with the
touch screen and automatically open <CODE>*.cv/*.cv.gz</CODE> files
from the file manager. ColEm-Maemo source code is included with the
core source code distribution.
<LI>Renamed <CODE>-zoom/-nozoom</CODE> to <CODE>-soft/-nosoft</CODE>.
<LI>Added <CODE>-scale</CODE> option to scale window on Unix.
<LI>Added <CODE>-home</CODE> to set home directory with system ROMs.
<LI>Options <CODE>-tv/-notv</CODE>, <CODE>-soft/-nosoft</CODE>, and the
<CODE>[F8]</CODE> key now work for both MSDOS and Unix.
<LI>ColEm-Symbian display routines rewritten in ARM assembler for speed.
<LI>Split ColEm-Symbian configuration menu into four tabs, making
"Video" and "Audio" settings separate.
<LI>Added "Audio Latency", "Skip Frames", and "Sync Updates" settings
to ColEm-Symbian.
<LI>Documentation and built-in help changed, many inconsistencies removed.
</UL>
<A NAME="LABC">
<H1>Introduction</H1>
</A>
<P>
ColEm is a portable emulator of the old ColecoVision videogame console.
It should run most ColecoVision games and supports Coleco's SuperAction
controllers with spin wheels. You can always get the latest ColEm binaries,
source code, and support files from
</P>
<P ALIGN=CENTER>
<A HREF="http://fms.komkon.org/ColEm/">http://fms.komkon.org/ColEm/</A>
</P>
<P>
There are versions of ColEm for many platforms, with Windows, MSDOS, Unix,
and Symbian ports being maintained by myself. All these ports are available
for free from the above website.
</P>
<P>
The ColEm-Symbian port works on the 3rd Edition Series60 phones from
Nokia and its licensees. You can download it, as well as my other
Symbian products, at
</P>
<P ALIGN=CENTER>
<A HREF="http://fms.komkon.org/EmuSymbian/">http://fms.komkon.org/EmuSymbian/</A>
</P>
<P>
ColEm is written in portable C and thus can be ported to any sufficiently
fast computing platform. The current ColEm source code distribution includes
portable core sources and platform-specific sources for Windows and MSDOS.
The ColEm-Unix sources are also available, for a slightly older version
of ColEm.
</P>
<P>
If you would like to port ColEm to another system or make changes in
ColEm's code, <U>please</U>, contact me by email or some other means. Be
aware that ColEm source code is freely distributable, but it is <U>not</U>
public domain and it is <U>not</U> released under GPL. You can not use it
for commercial purposes, distribute, or change it on your own, unless you
contact me to arrange the conditions of such use and get my permission.
Feel free to look at it though.
</P>
<A NAME="LABH">
<H1>Buttons</H1>
</A>
<FONT COLOR="#000060">
<PRE>
<B>All versions:</B>
[ALT] - Hold to switch to the second controller
[SPACE] - FIRE-R button (also: [SHIFT],A,S,D,F,G,H,J,K,L)
[CONTROL] - FIRE-L button (also: Z,X,C,V,B,N,M)
[Q] - SuperAction PURPLE button (also: E,T,U,O)
[W] - SuperAction BLUE button (also: R,Y,I,P)
[0]-[9] - Digit buttons
[-] - [*] button
[=] - [#] button
[PGUP] - Fast-forward emulation (also: [F9])
[ESC] - Quit emulation (also: [F12])
[F2] - Turn soundtrack log on/off
[F3] - Toggle FIRE-R autofire on/off
[F4] - Toggle FIRE-L autofire on/off
[F5] - Invoke configuration menu
[F6] - Load emulation state
[F7] - Save emulation state
[F9] - Fast-forward emulation (also: [PGUP])
[F11] - Reset hardware
[F12] - Quit emulation (also: [ESC])
[ALT]+[PGUP] - Increase audio volume
[ALT]+[PGDOWN] - Decrease audio volume
<B>With #define DEBUG:</B>
[F1] - Go into the built-in debugger
<B>With #define GIFLIB:</B>
[F10] - Make a screen snapshot (SNAPxxxx.GIF)
<B>With #define WINDOWS:</B>
[ALT]+[ENTER] - Switch between full screen and window modes
<B>With #define MSDOS or UNIX:</B>
[F8] - Turn scanline simulation on/off
[CTRL]+[F8] - Toggle screen softening on/off
</PRE>
</FONT>
<A NAME="LABI">
<H1>Command Line Options</H1>
</A>
<FONT COLOR="#000060">
<PRE>
Usage: colem [-option1 [-option2...]] [filename]
[filename] = Name of the file to load as a cartridge [CART.ROM]
This program will transparently uncompress singular GZIPped
and PKZIPped files.
<B>[-option] =</B>
-verbose <level> - Select debugging messages [5]
0 - Silent 1 - Startup messages
2 - VDP 4 - Illegal Z80 ops
16 - Sound
-skip <percent> - Percentage of frames to skip [25]
-help - Print this help page
-home <dirname> - Set directory with system ROM files [off]
-pal/-ntsc - Video system to use [-ntsc]
-adam/-cv - Run in Adam/ColecoVision mode [-cv]
-allspr - Show all sprites [off]
-autoa/-noautoa - Autofire/No autofire for FIRE-R button [-noautoa]
-autob/-noautob - Autofire/No autofire for FIRE-L button [-noautob]
-spin1x/-spin1y - Mouse X/Y position as SuperAction spinner 1 [off]
-spin2x/-spin2y - Mouse X/Y position as SuperAction spinner 2 [off]
-drums/-nodrums - Hit/Don't hit MIDI drums on noise [-nodrums]
-logsnd <filename> - Write soundtrack to a MIDI file [LOG.MID]
-palette <number> - Use given color palette [0]
0 - Scaled VDP colors 1 - Original VDP colors
2 - Faded NTSC colors
-sound [<quality>] - Sound emulation quality [22050]
-nosound - Don't emulate sound [-nosound]
<B>With #define DEBUG:</B>
-trap <address> - Trap execution when PC reaches address [FFFFh]
<B>With #define UNIX or MSDOS:</B>
-sync <frequency> - Sync screen updates to <frequency> [-nosync]
-nosync - Do not sync screen updates [-nosync]
-tv/-notv - Simulate/Don't simulate scanlines [-notv]
-soft/-nosoft - Scale screen up with softening [-nosoft]
<B>With #define MSDOS:</B>
-vsync - Sync screen updates to VGA VBlanks [-vsync]
<B>With #define UNIX:</B>
-saver/-nosaver - Save/don't save CPU when inactive [-saver]
-scale <factor> - Scale window by <factor> [2]
<B>With #define MITSHM:</B>
-shm/-noshm - Use/don't use MIT SHM extensions for X [-shm]
</PRE>
</FONT>
<A NAME="LABJ">
<H1>Frequently Asked Questions</H1>
</A>
<OL>
<LI><B>Why is the emulator so slow on my PC?</B>
<P>
Your computer may be too slow to run the emulator. On slow machines, try
speeding things up by skipping more frames (<CODE>-skip</CODE> command
line option or "Draw XX% frames" menu option). In ColEm-Windows, make
window smaller or switch to the full screen mode with
<CODE>[Alt]+[Enter]</CODE>.
</P>
<LI><B>Emulator is too fast on my PC!</B>
<P>
If ColEm is too fast on your computer, you can slow it down by syncing it
to a timer (<CODE>-sync</CODE> in ColEm-Unix), VBlanks (<CODE>-vsync</CODE>
in ColEm-MSDOS), or by choosing "PAL Video"/"NTSC Video" menu option in
ColEm-Windows.
</P>
<LI><B>I can't get some ROM images to work with the emulator.</B>
<P>
If you can't get ROM image to work, send it to me for analysis.
</P>
<LI><B>Is it legal to spread cartridge ROMs?</B>
<P>
<U>NO</U>. Nobody seems to care though, mainly because there is no
profit to be made from ColecoVision software any longer. Nevertheless, be
aware of the fact that by using commercial software you haven't bought you
are commencing an act of piracy.
</P>
<LI><B>When compiling ColEm-Unix, I get "undefined name" errors.</B>
<P>
This usually means that your linker cannot find the necessary libraries
(namely, libX11 and libXext) or some additional libraries (like libsocket
and libnsl) are required. Find these libraries in your system and modify
the Makefile so that the final invocation of the C compiler has
<CODE>-L<path_to_libs></CODE> options. If you have no libXext
library and the same functionality isn't provided in libX11, try
#undefining the <CODE>MITSHM</CODE> option.
</P>
<LI><B>When starting ColEm-Unix, I get X_ShmAttach error.</B>
<P>
You are probably trying to run the emulator on a remote Xterminal while
it attempts to use shared memory for interfacing with X. Another reason
for this error may be the lack of MITSHM extension support in your
Xserver. Use <CODE>-noshm</CODE> option to disable the usage of shared
memory.
</P>
<LI><B>When starting ColEm-Unix, I get X_PutImage error.</B>
<P>
Unix/X version of ColEm can currently be compiled for 8bit, 16bit, or
32bit Xterminals. Neither 1bit nor 4bit Xterminals will work with the
drivers included into official ColEm distribution.
</P>
</OL>
<A NAME="LABK">
<H1>History</H1>
</A>
<H2>New in ColEm 2.4</H2>
<UL>
<LI>Ported ColEm to smartphones running <B>Symbian/UIQ3</B> software!
<LI>Added new, much better, scanline simulation and video softening
effects to ColEm-Windows.
<LI>ColEm-Windows full-screen mode now runs in 640x480 resolution.
<LI>Added <CODE>-sync/-nosync</CODE> option to ColEm-MSDOS to sync screen
updates to the timer (use <CODE>-vsync</CODE> for VBlanks).
<LI>Added <CODE>-zoom/-nozoom</CODE> option to ColEm-MSDOS that will
zoom ColEm display to fill the whole screen, using image
softening algorithm.
<LI>ColEm-MSDOS now runs in 640x480x15bpp VESA screen mode when
<CODE>-zoom</CODE> or <CODE>-tv</CODE> options used, otherwise
it runs in 320x200x15bpp screen mode.
<LI>Added [CONTROL]+[F8] key combination to ColEm-MSDOS to toggle
display zoom on/off.
<LI>Added new "Fill & Soften" zoom mode to ColEm-Symbian. It is
rather slow though.
<LI>Fixed possible source of instabilities in the S60 open file dialog
in ColEm-Symbian.
</UL>
<H2>New in ColEm 2.3</H2>
<UL>
<LI>Added <B>network play</B> option to ColEm-Windows and ColEm-Symbian!
<LI>Now resetting R register on ResetZ80() to keep states of both NetPlay
players consistent.
<LI>Now clearing all RAM on ResetColeco() to keep states of both NetPlay
players consistent.
<LI>Added new, much better, scanline simulation and video softening
effects to ColEm-Windows.
<LI>ColEm-Windows full-screen mode now runs in 640x480 resolution.
<LI>Added zoom settings to ColEm-Symbian ("None", "Keep Aspect", and
"Fill Screen").
<LI>Added display orientation settings to ColEm-Symbian ("Landscape",
"Portrait", and "Auto").
<LI>Finally fixed opendir() problem in EMULib-Symbian. All built-in
menu file dialogs work now!
<LI>Further extended and optimized Symbian screen rendering routines.
<LI>Fixed and optimized TV scanline simulation in ColEm-Symbian, made
scanline effect stronger.
<LI>Fixed system warnings in when flipping Nokia E70 open/closed.
<LI>Fixed possible crash when selecting an initial file in ColEm-Symbian.
</UL>
<H2>New in ColEm 2.2</H2>
<UL>
<LI>Changed Z80 NMI handling to comply with the standard.
<LI>Added "show all sprites" option (-allspr).
<LI>Added error messages to ColEm-Windows and ColEm-Symbian.
<LI>Added button and key remapping configuration to ColEm-Symbian.
<LI>ColEm-Symbian application menu is now split into three pages.
<LI>ColEm-MSDOS is now prebound with DOS32A extender, instead of
outdated DOS4GW.
</UL>
<H2>New in ColEm 2.1</H2>
<UL>
<LI>Added builtin configuration menu ([F5]).
<LI>Added palette selection (-palette) between scaled VDP palette, original
VDP palette, and the faded NTSC palette suggested by Richard Drushel.
<LI>Now defaulting to the palette from TMS9918 datasheet scaled by 255/224
to get true white color.
<LI>Fixed console keyboard input in Windows.
<LI>Updated and extended documentation.
</UL>
<H2>New in ColEm 2.0</H2>
<UL>
<LI>MSDOS and Windows versions are now based on the new framework.
<LI>Started adding Coleco Adam emulation (not finished yet).
<LI>Added state saving and loading via .STA files.
<LI>Added SuperAction spinner emulation with the mouse.
<LI>Added zoomed sprites support in VDP.
<LI>Standardized TMS9918 emulation.
<LI>Fixed VDP VBlank interrupt bug.
<LI>Replaced "updates per VBlank" (-uperiod) with "percentage of
skipped frames" parameter (-skip).
<LI>Removed -vperiod/-hperiod parameters as deprecated.
<LI>Added -pal/-ntsc parameters to switch between TMS9918/TMS9928
and TMS9929 VDPs.
<LI>Soundtrack saved into MIDI files.
<LI>Documentation rewritten in HTML.
<LI>Added speed throttling to ColEm-MSDOS (-vsync).
<LI>Keyboard assignments have changed.
</UL>
<H2>New in ColEm 1.0</H2>
<UL>
<LI>Standardized Z80 emulation.
<LI>Standardized PSG emulation.
<LI>Soundtrack saved into .SND files.
<LI>Screen refresh done line-by-line.
<LI>Sprites are refreshed line-by-line.
<LI>Limit on sprites per line introduced.
<LI>General cleanup of the source code.
<LI>Rewritten documentation.
</UL>
<A NAME="LABI">
<H1>Thanks to...</H1>
</A>
<P>
Finally, I would like to thank Hans Guijt, Marcel de Kogel, John Stiles,
Neal Danner, Alan Steremberg, and all other people who helped me with
advice, information, ROM images, and encouragment.
</P>
<HR>
<I>
© Copyright by
<A HREF="http://fms.komkon.org/">Marat Fayzullin</A>
(marat [AT] komkon /DOT/ org)
</I>
</BODY>
</HTML>
|
