Sprinter/mame
2
0
Fork 0
mirror of https://github.com/holub/mame synced 2025-06-14 00:25:38 +03:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

remove old doc content (nw)

Browse Source
This commit is contained in:
Miodrag Milanovic 2016-08-24 15:14:30 +02:00
parent bade8ef9a9
commit a86a53fb64
14 changed files with 0 additions and 4649 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/LICENSE
View File

@ -1,116 +0,0 @@
CC0 1.0 Universal
Statement of Purpose
The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator and
subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").
Certain owners wish to permanently relinquish those rights to a Work for the
purpose of contributing to a commons of creative, cultural and scientific
works ("Commons") that the public can reliably and without fear of later
claims of infringement build upon, modify, incorporate in other works, reuse
and redistribute as freely as possible in any form whatsoever and for any
purposes, including without limitation commercial purposes. These owners may
contribute to the Commons to promote the ideal of a free culture and the
further production of creative, cultural and scientific works, or to gain
reputation or greater distribution for their Work in part through the use and
efforts of others.
For these and/or other purposes and motivations, and without any expectation
of additional consideration or compensation, the person associating CC0 with a
Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
and publicly distribute the Work under its terms, with knowledge of his or her
Copyright and Related Rights in the Work and the meaning and intended legal
effect of CC0 on those rights.
1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not limited
to, the following:
i. the right to reproduce, adapt, distribute, perform, display, communicate,
and translate a Work;
ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or likeness
depicted in a Work;
iv. rights protecting against unfair competition in regards to a Work,
subject to the limitations in paragraph 4(a), below;
v. rights protecting the extraction, dissemination, use and reuse of data in
a Work;
vi. database rights (such as those arising under Directive 96/9/EC of the
European Parliament and of the Council of 11 March 1996 on the legal
protection of databases, and under any national implementation thereof,
including any amended or successor version of such directive); and
vii. other similar, equivalent or corresponding rights throughout the world
based on applicable law or treaty, and any national implementations thereof.
2. Waiver. To the greatest extent permitted by, but not in contravention of,
applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
and Related Rights and associated claims and causes of action, whether now
known or unknown (including existing as well as future claims and causes of
action), in the Work (i) in all territories worldwide, (ii) for the maximum
duration provided by applicable law or treaty (including future time
extensions), (iii) in any current or future medium and for any number of
copies, and (iv) for any purpose whatsoever, including without limitation
commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
the Waiver for the benefit of each member of the public at large and to the
detriment of Affirmer's heirs and successors, fully intending that such Waiver
shall not be subject to revocation, rescission, cancellation, termination, or
any other legal or equitable action to disrupt the quiet enjoyment of the Work
by the public as contemplated by Affirmer's express Statement of Purpose.
3. Public License Fallback. Should any part of the Waiver for any reason be
judged legally invalid or ineffective under applicable law, then the Waiver
shall be preserved to the maximum extent permitted taking into account
Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
is so judged Affirmer hereby grants to each affected person a royalty-free,
non transferable, non sublicensable, non exclusive, irrevocable and
unconditional license to exercise Affirmer's Copyright and Related Rights in
the Work (i) in all territories worldwide, (ii) for the maximum duration
provided by applicable law or treaty (including future time extensions), (iii)
in any current or future medium and for any number of copies, and (iv) for any
purpose whatsoever, including without limitation commercial, advertising or
promotional purposes (the "License"). The License shall be deemed effective as
of the date CC0 was applied by Affirmer to the Work. Should any part of the
License for any reason be judged legally invalid or ineffective under
applicable law, such partial invalidity or ineffectiveness shall not
invalidate the remainder of the License, and in such case Affirmer hereby
affirms that he or she will not (i) exercise any of his or her remaining
Copyright and Related Rights in the Work or (ii) assert any associated claims
and causes of action with respect to the Work, in either case contrary to
Affirmer's express Statement of Purpose.
4. Limitations and Disclaimers.
a. No trademark or patent rights held by Affirmer are waived, abandoned,
surrendered, licensed or otherwise affected by this document.
b. Affirmer offers the Work as-is and makes no representations or warranties
of any kind concerning the Work, express, implied, statutory or otherwise,
including without limitation warranties of title, merchantability, fitness
for a particular purpose, non infringement, or the absence of latent or
other defects, accuracy, or the present or absence of errors, whether or not
discoverable, all to the greatest extent permissible under applicable law.
c. Affirmer disclaims responsibility for clearing rights of other persons
that may apply to the Work or any use thereof, including without limitation
any person's Copyright and Related Rights in the Work. Further, Affirmer
disclaims responsibility for obtaining any necessary consents, permissions
or other rights required for any use of the Work.
d. Affirmer understands and acknowledges that Creative Commons is not a
party to this document and has no duty or obligation with respect to this
CC0 or use of the Work.
For more information, please see
<http://creativecommons.org/publicdomain/zero/1.0/>

5
docs/README.md
View File

@ -1,5 +0,0 @@
# **Docs** #
Documentation of MAME is work of many different contributors, and contain information about usage and internals of MAME.
Licensed under [CC0 1.0 Universal (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/)

376
docs/SDL.txt
View File

@ -1,376 +0,0 @@
This file describes SDL-specific usage information about MAME. It is
intended to cover aspects of using and configuring the program that are
specific to running MAME from the command line on any system which is
supported by SDL (including Windows).
In addition to the keys described in config.txt, the following additional
keys are defined for SDL-specific versions of MAME:
Debugging options
-----------------
-[no]oslog
Outputs the error.log data to the stderr TTY channel (usually the
command line window MAME was started in). This can be used at
the same time as -log to output the log data to both targets as well.
Default is OFF (-nooslog).
-watchdog <duration> / -wdog <duration>
Enables an internal watchdog timer that will automatically kill the MAME
process if more than <duration> seconds passes without a frame update.
Keep in mind that some games sit for a while during load time without
updating the screen, so <duration> should be long enough to cover that.
10-30 seconds on a modern system should be plenty in general. By default
there is no watchdog.
Performance options
-------------------
-[no]multithreading / -[no]mt
Enables multithreading for the final drawing operation. This can help
performance on multicore/hyperthreaded systems with slow video cards,
but may cause undesired behavior in some games.
Note that some drivers in MAME and MESS will use multiple threads even
when this is set to OFF, assuming -numprocessors allows it.
The default is OFF (-nomultithreading).
-numprocessors <auto|value> / -np <auto|value>
Specify the number of processors to use for work queues. Specifying
"auto" will use the value reported by the system or environment
variable OSDPROCESSORS. To avoid abuse, this value is internally limited
to 4 times the number of processors reported by the system.
The default is "auto".
-sdlvideofps
Enable output of benchmark data on the SDL video subsystem, including
your system's video driver, X server (if applicable), and OpenGL stack
in -video opengl mode.
-bench [n]
Benchmark for [n] number of emulated seconds; implies the command string:
-str [n] -video none -sound none -nothrottle. Default is OFF (-nobench)
Video options
-------------
-video <soft|opengl|none>
Specifies which video subsystem to use for drawing. The default for
Mac OS X is 'opengl' because OS X is guaranteed to have a compliant
OpenGL stack. The default on all other systems is 'soft'.
-numscreens <count>
Tells MAME how many output windows to create. For most games, a single
output window is all you need, but some games originally used multiple
screens. Each screen (up to 4) has its own independent settings for
physical monitor, aspect ratio, resolution, and view, which can be
set using the options below. The default is 1. SDL currently has a
limit of 1 with the expectation of increasing this when SDL 2.0 is
released.
-[no]window / -[no]w
Run MAME in either a window or full screen. The default is OFF
(-nowindow).
-[no]maximize / -[no]max
Controls initial window size in windowed mode. If it is set on, the
window will initially be set to the maximum supported size when you
start MAME. If it is turned off, the window will start out at the
smallest supported size. This option only has an effect when the
-window option is used. The default is ON (-maximize).
-[no]keepaspect / -[no]ka
Enables aspect ratio enforcement. When this option is on, the game's
proper aspect ratio (generally 4:3 or 3:4) is enforced, so you get the
game looking like it should. When running in a window with this option
on, you can only resize the window to the proper aspect ratio, unless
you are holding down the CONTROL key. By turning the option off, the
aspect ratio is allowed to float. In full screen mode, this means that
all games will stretch to the full screen size (even vertical games).
In window mode, it means that you can freely resize the window without
any constraints. The default is ON (-keepaspect).
-[no]unevenstretch
Allow non-integer stretch factors allowing for great window sizing
flexability. The default is ON. (-unevenstretch)
-[no]centerh
Center horizontally within the view area. Default is ON (-centerh).
-[no]centerv
Center vertically within the view area. Default is ON (-centerv).
-[no]waitvsync
Waits for the refresh period on your computer's monitor to finish
before starting to draw video to your screen. If this option is off,
MAME will just draw to the screen at any old time, even in the middle
of a refresh cycle. This can cause "tearing" artifacts, where the top
portion of the screen is out of sync with the bottom portion. Tearing
is not noticeable on all games, and some people hate it more than
others. However, if you turn this option on, you will waste more of
your CPU cycles waiting for the proper time to draw, so you will see a
performance hit. You should only need to turn this on in windowed mode.
In full screen mode, it is only needed if -triplebuffer does not
remove the tearing, in which case you should use -notriplebuffer
-waitvsync. Note that support for this option depends entirely on your
operating system and video drivers; in general it will not work in
windowed mode so -video opengl and fullscreen give the greatest chance
of success.
The default is OFF (-nowaitvsync).
-[no]syncrefresh
Enables speed throttling only to the refresh of your monitor. This
means that the game's actual refresh rate is ignored; however, the
sound code still attempts to keep up with the game's original refresh
rate, so you may encounter sound problems. This option is intended
mainly for those who have tweaked their video card's settings to
provide carefully matched refresh rate options. Note that this option
does not work with -video gdi mode.The default is OFF (-nosyncrefresh).
Video soft-specific options
---------------------------
-scalemode
Scale mode: none, async, yv12, yuy2, yv12x2, yuy2x2 (-video soft only)
Default is 'none'.
Video OpenGL-specific options
-----------------------------
-[no]filter / -[no]flt
Enable bilinear filtering on the game screen graphics. When disabled,
point filtering is applied, which is crisper but leads to scaling
artifacts. If you don't like the filtered look, you are probably better
off increasing the -prescale value rather than turning off filtering
altogether. The default is ON (-filter).
-prescale <amount>
Controls the size of the screen images when they are passed off to the
graphics system for scaling. At the minimum setting of 1, the screen
is rendered at its original resolution before being scaled. At higher
settings, the screen is expanded by a factor of <amount> before being
scaled. This produces a less blurry image at the expense of some speed
and also increases the effective resolution of non-screen elements such
as artwork and fonts. The default is 1.
-[no]gl_forcepow2texture Always use only power-of-2 sized textures (default off)
-[no]gl_notexturerect Don't use OpenGL GL_ARB_texture_rectangle (default on)
-[no]gl_vbo Enable OpenGL VBO, if available (default on)
-[no]gl_pbo Enable OpenGL PBO, if available (default on)
These 4 options are for compatibility in -video opengl. If you report
rendering artifacts you may be asked to try messing with them by the
devs, but normally they should be left at their defaults which results
in the best possible video performance.
-gl_glsl Enable OpenGL GLSL, if available (default off)
-gl_glsl_filter Enable OpenGL GLSL filtering instead of FF filtering 0-plain,
1-bilinear (default)
-glsl_shader_mame0 Custom OpenGL GLSL shader set mame bitmap 0
-glsl_shader_mame1 Custom OpenGL GLSL shader set mame bitmap 1
-glsl_shader_mame2 Custom OpenGL GLSL shader set mame bitmap 2
-glsl_shader_mame3 Custom OpenGL GLSL shader set mame bitmap 3
-glsl_shader_mame4 Custom OpenGL GLSL shader set mame bitmap 4
-glsl_shader_mame5 Custom OpenGL GLSL shader set mame bitmap 5
-glsl_shader_mame6 Custom OpenGL GLSL shader set mame bitmap 6
-glsl_shader_mame7 Custom OpenGL GLSL shader set mame bitmap 7
-glsl_shader_mame8 Custom OpenGL GLSL shader set mame bitmap 8
-glsl_shader_mame9 Custom OpenGL GLSL shader set mame bitmap 9
-glsl_shader_screen0 Custom OpenGL GLSL shader screen bitmap 0
-glsl_shader_screen1 Custom OpenGL GLSL shader screen bitmap 1
-glsl_shader_screen2 Custom OpenGL GLSL shader screen bitmap 2
-glsl_shader_screen3 Custom OpenGL GLSL shader screen bitmap 3
-glsl_shader_screen4 Custom OpenGL GLSL shader screen bitmap 4
-glsl_shader_screen5 Custom OpenGL GLSL shader screen bitmap 5
-glsl_shader_screen6 Custom OpenGL GLSL shader screen bitmap 6
-glsl_shader_screen7 Custom OpenGL GLSL shader screen bitmap 7
-glsl_shader_screen8 Custom OpenGL GLSL shader screen bitmap 8
-glsl_shader_screen9 Custom OpenGL GLSL shader screen bitmap 9
-gl_glsl_vid_attr Enable OpenGL GLSL handling of brightness and contrast.
Better RGB game performance. Default is on.
Per-window options
------------------
NOTE: Multiple Screens are limited to 1 until SDL 2.0 is released.
-screen <display>
-screen0 <display>
-screen1 <display>
-screen2 <display>
-screen3 <display>
Specifies which physical monitor on your system you wish to have each
window use by default. In order to use multiple windows, you must have
increased the value of the -numscreens option. The name of each
display in your system can be determined by running MAME with the
-verbose option. The display names are typically in the format of:
\\.\DISPLAYn, where 'n' is a number from 1 to the number of connected
monitors. The default value for these options is 'auto', which means
that the first window is placed on the first display, the second
window on the second display, etc.
The -screen0, -screen1, -screen2, -screen3 parameters apply to the
specific window. The -screen parameter applies to all windows. The
window-specific options override values from the all window option.
-aspect <width:height> / -screen_aspect <num:den>
-aspect0 <width:height>
-aspect1 <width:height>
-aspect2 <width:height>
-aspect3 <width:height>
Specifies the physical aspect ratio of the physical monitor for each
window. In order to use multiple windows, you must have increased the
value of the -numscreens option. The physical aspect ratio can be
determined by measuring the width and height of the visible screen
image and specifying them separated by a colon. The default value for
these options is 'auto', which means that MAME assumes the aspect
ratio is proportional to the number of pixels in the desktop video
mode for each monitor.
The -aspect0, -aspect1, -aspect2, -aspect3 parameters apply to the
specific window. The -aspect parameter applies to all windows. The
window-specific options override values from the all window option.
-resolution <widthxheight[@refresh]> / -r <widthxheight[@refresh]>
-resolution0 <widthxheight[@refresh]> / -r0 <widthxheight[@refresh]>
-resolution1 <widthxheight[@refresh]> / -r1 <widthxheight[@refresh]>
-resolution2 <widthxheight[@refresh]> / -r2 <widthxheight[@refresh]>
-resolution3 <widthxheight[@refresh]> / -r3 <widthxheight[@refresh]>
Specifies an exact resolution to run in. In full screen mode, MAME
will try to use the specific resolution you request. The width and
height are required; the refresh rate is optional. If omitted or
set to 0, MAME will determine the mode auomatically. For example,
-resolution 640x480 will force 640x480 resolution, but MAME is free to
choose the refresh rate. Similarly, -resolution 0x0@60 will force a
60Hz refresh rate, but allows MAME to choose the resolution. The
string "auto" is also supported, and is equivalent to 0x0@0. In window
mode, this resolution is used as a maximum size for the window. This
option requires the -switchres option as well in order to actually
Enable resolution switching.
The -resolution0, -resolution1, -resolution2, -resolution3 parameters
apply to the specific window. The -resolution parameter applies to all
windows. The window-specific options override values from the all
window option.
-view <viewname>
-view0 <viewname>
-view1 <viewname>
-view2 <viewname>
-view3 <viewname>
Specifies the initial view setting for each window. The <viewname>
does not need to be a perfect match; rather, it will select the first
view whose name matches all the characters specified by <viewname>.
For example, -view native will match the "Native (15:14)" view even
though it is not a perfect match. The value 'auto' is also supported,
and requests that MAME perform a default selection. The default value
for these options is 'auto'.
The -view0, -view1, -view2, -view3 parameters apply to the
specific window. The -view parameter applies to all windows. The
window-specific options override values from the all window option.
Full screen options
-------------------
-[no]switchres
Enables resolution switching. This option is required for the
-resolution* options to switch resolutions in full screen mode. On
modern video cards, there is little reason to switch resolutions unless
you are trying to achieve the "exact" pixel resolutions of the original
games, which requires significant tweaking. This option is also useful
on LCD displays, since they run with a fixed resolution and switching
resolutions on them is just silly.
The default is OFF (-noswitchres).
Sound options
-------------
-sound <sdl|none>
Specifies which sound subsystem to use. 'none' disables sound altogether.
The default is sdl.
-audio_latency <value>
This controls the amount of latency built into the audio streaming. By
default MAME tries to keep the audio buffer between 1/5 and 2/5 full.
On some systems, this is pushing it too close to the edge, and you get
poor sound sometimes. The latency parameter controls the lower threshold.
The default is 2 (meaning lower=2/5 and upper=3/5). Set it to 3
(-audio_latency 3) to keep the sound buffer between 3/5 and 4/5 full.
If you crank it up to 4, you can definitely notice the lag.
SDL Keyboard Mapping
--------------------
-keymap Enable keymap. Default is OFF (-nokeymap)
-keymap_file Keymap Filename. Default is 'keymap.dat'.
-uimodekey Key to toggle keyboard mode. Default is 'SCRLOCK'
SDL Joystick Mapping
--------------------
-joy_idx1 Name of joystick mapped to joystick #1, default is auto.
-joy_idx2 Name of joystick mapped to joystick #2, default is auto.
-joy_idx3 Name of joystick mapped to joystick #3, default is auto.
-joy_idx4 Name of joystick mapped to joystick #4, default is auto.
-joy_idx5 Name of joystick mapped to joystick #5, default is auto.
-joy_idx6 Name of joystick mapped to joystick #6, default is auto.
-joy_idx7 Name of joystick mapped to joystick #7, default is auto.
-joy_idx8 Name of joystick mapped to joystick #8, default is auto.
-sixaxis Use special handling for PS3 Sixaxis controllers.
Default is OFF (-nosixaxis)
SDL Lowlevel driver options
---------------------------
-videodriver SDL video driver to use ('x11', 'directfb', ... or 'auto' for SDL default
-audiodriver SDL audio driver to use ('alsa', 'arts', ... or 'auto' for SDL default
-gl_lib Alternative libGL.so to use; 'auto' for system default

1264
docs/config.txt
View File

File diff suppressed because it is too large Load Diff

60
docs/emscripten.txt
View File

@ -1,60 +0,0 @@
Compiling MAME to JavaScript via Emscripten
===========================================
First, download and install Emscripten by following the instructions at the
official site:
https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html
Once Emscripten has been installed, it should be possible to compile MAME
out-of-the-box using Emscripten's 'emmake' tool. Because a full MAME compile is
too large to load into a web browser at once, you will want to use the SOURCES
parameter to compile only a subset of the project, e.g. (in the mame directory):
emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/pacman.cpp
The SOURCES parameter should have the path to at least one driver .cpp file.
The make process will attempt to locate and include all dependencies necessary
to produce a complete build including the specified driver(s). However,
sometimes it is necessary to manually specify additional files (using commas) if
this process misses something. E.g.:
emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp
The value of the SUBTARGET parameter serves only to differentiate multiple
builds and need not be set to any specific value.
Other make parameters can also be used, e.g. -j for multithreaded compilation.
When the compilation reaches the emcc phase, you may see a number of "unresolved
symbol" warnings. At the moment, this is expected for OpenGL-related functions
such as glPointSize. Any others may indicate that an additional dependency file
needs to be specified in the SOURCES list. Unfortunately this process is not
automated and you will need to search the source tree to locate the files
supplying the missing symbols. You may also be able to get away with ignoring
the warnings if the code path referencing them is not used at run-time.
If all goes well, a .js file will be output to the current directory. This file
cannot be run by itself, but requires an HTML loader to provide it with a canvas
to output to and pass in command-line parameters. The Emularity project provides
such a loader:
https://github.com/db48x/emularity
There are example .html files in that repository which can be edited to point
to your newly compiled MAME js filename and pass in whatever parameters you
desire. You will then need to place all of the following on a web server:
* The compiled MAME .js file
* The .js files from the Emularity package (loader.js, browserfs.js, etc.)
* A .zip file with the ROMs for the MAME driver you would like to run (if any)
* Any software files you would like to run with the MAME driver
* An Emularity loader .html modified to point to all of the above
You need to use a web server instead of opening the local files directly due to
security restrictions in modern web browsers.
If the result fails to run, you can open the Web Console in your browser to see
any error output which may have been produced (e.g. missing or incorrect ROM
files). A "ReferenceError: foo is not defined" error most likely indicates that
a needed source file was omitted from the SOURCES list.

633
docs/floppy.txt
View File

@ -1,633 +0,0 @@
The new floppy subsystem
------------------------
1. Introduction
The new floppy subsystem aims at emulating the behaviour of floppies
and floppy controllers at a level low enough that protections work as
a matter of course. It reaches its goal by following the real
hardware configuration:
- a floppy image class keeps in memory the magnetic state of the
floppy surface and its physical characteristics
- an image handler class talks with the floppy image class to simulate
the floppy drive, providing all the signals you have on a floppy drive
connector
- floppy controller devices talk with the image handler and provide
the register interfaces to the host we all know and love
- format handling classes are given the task of statelessly converting
to and from an on-disk image format to the in-memory magnetic state
format the floppy image class manages
2. Floppy storage 101
2.1. Floppy disk
A floppy disk is a disc that stores magnetic orientations on their
surface disposed in a series on concentric circles called tracks or
cylinders[1]. Its main characteristics are its size (goes from a
diameter of around 2.8" to 8") , its number of writable sides (1 or 2)
and its magnetic resistivity. The magnetic resistivity indicates how
close magnetic orientation changes can happen and the information
kept. That's one third of what defines the term "density" that is so
often used for floppies (the other two are floppy drive head size and
bit-level encoding).
The magnetic orientations are always binary, e.g. they're one way or
the opposite, there's no intermediate state. Their direction can
either be tengentially to the track, e.g in the direction or opposite
to the rotation, or in the case of perpendicular recording the
direction is perpendicular to the disc surface (hence the name).
Perpendicular recording allows for closer orientation changes by
writing the magnetic information more deeply, but arrived late in the
technology lifetime. 2.88Mb disks and the floppy children (Zip
drives, etc) used perpendicular recording. For simulation purposes
the direction is not important, only the fact that only two
orientations are possible is. Two more states are possible though: a
portion of a track can be demagnetized (no orientation) or damaged (no
orientation and can't be written to).
A specific position in the disk rotation triggers an index pulse.
That position can be detected through a hole in the surface (very
visible in 5.25" and 3" floppies for instance) or through a specific
position of the rotating center (3.5" floppies, perhaps others). This
index pulse is used to designate the beginning of the track, but is
not used by every system. Older 8" floppies have multiple index holes
used to mark the beginning of sectors (called hard sectoring) but one
of them is positioned differently to be recognized as the track start,
and the others are at fixed positions relative to the origin one.
2.2 Floppy drive
A floppy drive is what reads and writes a floppy disk. It includes an
assembly capable of rotating the disk at a fixed speed and one or two
magnetic heads tied to a positioning motor to access the tracks.
The head width and positioning motor step size decides how many tracks
are written on the floppy. Total number of tracks goes from 32 to 84
depending on the floppy and drive, with the track 0 being the most
exterior (longer) one of the concentric circles, and the highest
numbered the smallest interior circle. As a result the tracks with
the lowest numbers have the lowest physical magnetic orientation
density, hence the best reliability. Which is why important and/or
often changed structures like the boot block or the fat allocation
table are at track 0. That is also where the terminology "stepping
in" to increase the track number and "stepping out" to decrease it
comes from. The number of tracks available is the second part of what
is usually behind the term "density".
A sensor detects when the head is on track 0 and the controller is not
supposed to try to go past it. In addition physical blocks prevent
the head from going out of the correct track range. Some systems
(Apple II, some C64) do not take the track 0 sensor into account and
just wham the head against the track 0 physical block, giving a
well-known crash noise and eventually damaging the head alignment.
Also, some systems (Apple II and C64 again) have direct access to the
phases of the head positioning motor, allowing to trick the head into
going between tracks, in middle or even quarter positions. That was
not usable to write more tracks, since the head width did not change,
but since reliable reading was only possible with the correct position
it was used for some copy protection systems.
The disk rotates at a fixed speed for a given track. The most usual
speed is 300 rpm for every track, with 360 rpm found for HD 5.25"
floppies and most 8" ones, and a number of different values like 90 rpm
for the earlier floppies or 150 rpm for an HD floppy in an Amiga.
Having a fixed rotational speed for the whole disk is called Constant
Angular Velocity (CAV, almost everybody) or Zoned Constant Angular
Velocity (ZCAV, C64) depending on whether the read/write bitrate is
constant or track-dependant. Some systems (Apple II, Mac) vary the
rotational speed depending on the track (something like 394 rpm up to
590 rpm) to end up with a Constant Linear Velocity (CLV). The idea
behind ZCAV/CLV is to get more bits out of the media by keeping the
minimal spacing between magnetic orientation transitions close to the
best the support can do. It seems that the complexity was not deemed
worth it since almost no system does it.
Finally, after the disc rotates and the head is over the proper track
reading happens. The reading is done through an inductive head, which
gives it the interesting characteristic of not reading the magnetic
orientation directly but instead of being sensitive to orientation
inversions, called flux transitions. This detection is weak and
somewhat uncalibrated, so an amplifier with Automatic Gain Calibration
(AGC) and a peak detector are put behind the head to deliver clean
pulses. The AGC slowly increases the amplification level until a
signal goes over the threshold, then modulates its gain so that said
signal is at a fixed position over the threshold. Afterwards the
increase happens again. This makes the amplifier calibrate itself to
the signals read from the floppy as long as flux transitions happen
often enough. Too long and the amplification level will reach a point
where the random noise the head picks from the environment is
amplified over the threshold, creating a pulse where none should be.
Too long in our case happens to be around 16-20us with no transitions.
That means a long enough zone with a fixed magnetic orientation or no
orientation at all (demagnetized or damaged) is going to be read as a
series of random pulses after a brief delay. This is used by
protections and is known as "weak bits", which read differently each
time they're accessed.
A second level of filtering happens after the peak detector. When two
transitions are a little close (but still over the media threshold) a
bouncing effect happens between them giving two very close pulses in
the middle in addition to the two normal pulses. The floppy drive
detects when pulses are too close and filter them out, leaving the
normal ones. As a result, if one writes a train of high-frequency
pulses to the floppy they will be read back as a train of too close
pulses (weak because they're over the media tolerance, but picked up
by the AGC anyway, only somewhat unreliably) they will be all filtered
out, giving a large amount of time without any pulse in the output
signal. This is used by some protections since it's not writable with
a normally clocked controller.
Writing is symmetrical, with a series of pulses sent which make the
write head invert the magnetic field orientation each time a pulse is
received.
So, in conclusion, the floppy drive provides inputs to control disk
rotation and head position (and choice when double-sided), and the
data goes both way as a train of pulses representing magnetic
orientation inversions. The absolute value of the orientation itself
is never known.
2.3 Floppy controller
The task of the floppy controller is to turn the signals to/from the
floppy drive into something the main CPU can digest. The level of
support actually done by the controller is extremely variable from one
device to the other, from pretty much nothing (Apple II, C64) through
minimal (Amiga) to complete (Western Digital chips, uPD765 family).
Usual functions include drive selection, motor control, track seeking
and of course reading and writing data. Of these only the last two
need to be described, the rest is obvious.
The data is structured at two levels: how individual bits (or nibbles,
or bytes) are encoded on the surface, and how these are grouped in
individually-addressable sectors. Two standards exist for these,
called FM and MFM, and in addition a number of systems use their
home-grown variants. Moreover, some systems such as the Amiga use a
standard bit-level encoding (MFM) but a homegrown sector-level
organisation.
2.3.1 Bit-level encodings
2.3.1.1 Cell organization
All floppy controllers, even the wonkiest like the Apple II one, start
by dividing the track in equally-sized cells. They're angular
sections in the middle of which a magnetic orientation inversion may
be present. From a hardware point of view the cells are seen as
durations, which combined with the floppy rotation give the section.
For instance the standard MFM cell size for a 3" double-density floppy
is 2us, which combined with the also standard 300 rpm rotational speed
gives an angular size of 1/100000th of a turn. Another way of saying
it is that there are 100K cells in a 3" DD track.
In every cell there may or may not be a magnetic orientation
transition, e.g. a pulse coming from (reading) or going to (writing)
the floppy drive. A cell with a pulse is traditionally noted '1', and
one without '0'. Two constraints apply to the cell contents though.
First, pulses must not be too close together or they'll blur
each-other and/or be filtered out. The limit is slightly better than
1/50000th of a turn for single and double density floppies, half that
for HD floppys, and half that again for ED floppies with perpendicular
recording. Second, they must not be too away from each other or
either the AGC is going to get wonky and introduce phantom pulses or
the controller is going to lose sync and get a wrong timing on the
cells on reading. Conservative rule of thumb is not to have more than
three consecutive '0' cells.
Of course protections play with that to make formats not reproducible
by the system controller, either breaking the three-zeroes rule or
playing with the cells durations/sizes.
Bit endocing is then the art of transforming raw data into a cell 0/1
configuration that respects the two constraints.
2.3.1.2 FM encoding
The very first encoding method developed for floppies is called
Frequency Modulation, or FM. The cell size is set at slighly over the
physical limit, e.g. 4us. That means it is possible to reliably have
consecutive '1' cells. Each bit is encoded on two cells:
- the first cell, called the clock bit, is '1'
- the second cell, called data bit, is the bit
Since every other cell at least is '1' there is no risk of going over
three zeroes.
The name Frequency Modulation simply derives from the fact that a 0 is
encoded with one period of a 125Khz pulse train while a 1 is two
periods of a 250Khz pulse train.
2.3.1.3 MFM encoding
The FM encoding has been superseded by the Modified Frequency
Modulation encoding, which can cram exactly twice as much data on the
same surface, hence its other name of "double density". The cell size
is set at slightly over half the physical limit, e.g. 2us usually.
The constraint means that two '1' cells must be separated by at least
one '0' cell. Each bit is once again encoded on two cells:
- the first cell, called the clock bit, is '1' if both the previous
and current data bits are 0, '0' otherwise
- the second cell, called data bit, is the bit
The minimum space rule is respected since a '1' clock bit is by
definition surrounded by two '0' data bits, and a '1' data bit is
surrounded by two '0' clock bits. The longest '0'-cell string
possible is when encoding 101 which gives x10001, respecting the
maximum of three zeroes.
2.3.1.4 GCR encodings
Group Coded Recording, or GCR, encodings are a class of encodings
where strings of bits at least nibble-size are encoded into a given
cell stream given by a table. It has been used in particular by the
Apple II, the Mac and the C64, and each system has its own table, or
tables.
2.3.1.5 Other encodings
Other encodings exist, like M2FM, but they're very rare and
system-specific.
2.3.1.6 Reading back encoded data
Writing encoded data is easy, you only need a clock at the appropriate
frequency and send or not a pulse on the clock edges. Reading back
the data is where the fun is. Cells are a logical construct and not a
physical measurable entity. Rotational speeds very around the defined
one (+/- 2% is not rare) and local perturbations (air turbulence,
surface distance...) make the instant speed very variable in general.
So to extract the cell values stream the controller must dynamically
synchronize with the pulse train that the floppy head picks up. The
principle is simple: a cell-sized duration window is build within
which the presence of at least one pulse indicates the cell is a '1',
and the absence of any a '0'. After reaching the end of the window
the starting time is moved appropriately to try to keep the observed
pulse at the exact middle of the window. This allows to correct the
phase on every '1' cell, making the synchronization work if the
rotational speed is not too off. Subsequent generations of
controllers used a Phase-Locked Loop (PLL) which vary both phase and
window duration to adapt better to wrong rotational speeds, with
usually a tolerance of +/- 15%.
Once the cell data stream is extracted decoding depends on the
encoding. In the FM and MFM case the only question is to recognize
data bits from clock bits, while in GCR the start position of the
first group should be found. That second level of synchronization is
handled at a higher level using patterns not found in a normal stream.
2.3.2 Sector-level organization
Floppies have been designed for read/write random access to reasonably
sized blocks of data. Track selection allows for a first level of
random access and sizing, but the ~6K of a double density track would
be too big a block to handle. 256/512 bytes are considered a more
appropriate value. To that end data on a track is organized as a
series of (sector header, sector data) pairs where the sector header
indicates important information like the sector number and size, and
the sector data contains the data. Sectors have to be broken in two
parts because while reading is easy, read the header then read the
data if you want it, writing requires reading the header to find the
correct place then once that is done switching on the writing head for
the data. Starting writing is not instantaneous and will not be
perfectly phase-aligned with the read header, so space for
synchronization is required between header and data.
In addition somewhere in the sector header and in the sector data are
pretty much always added some kind of checksum allowing to know
whether the data was damaged or not.
FM and MFM have (not always used) standard sector layout methods.
2.3.2.1 FM sector layout
The standard "PC" track/sector layout for FM is as such:
- A number of FM-encoded 0xff (usually 40)
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
- The 16-cell stream 1111011101111010 (f77a, clock 0xd7, data 0xfc)
- A number of FM-encoded 0xff (usually 26, very variable)
Then for each sector:
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
- The 16-cell stream 1111010101111110 (f57e, clock 0xc7, data 0xfe)
- Sector header, e.g. FM encoded track, head, sector, size code and two bytes of crc
- 11 FM-encoded 0xff
- 6 FM-encoded 0x00 (giving a steady 125KHz pulse train)
- The 16-cell stream 1111010101101111 (f56f, clock 0xc7, data 0xfb)
- FM-encoded sector data followed by two bytes of crc
- A number of FM-encoded 0xff (usually 48, very variable)
The track is finished with a stream of '1' cells.
The 125KHz pulse trains are used to lock the PLL to the signal
correctly. The specific 16-cells streams allow to distinguish between
clock and data bits by providing a pattern that is not supposed to
happen in normal FM-encoded data. In the sector header track numbers
start at 0, heads are 0/1 depending on the size, sector numbers
usually start at 1 and size code is 0 for 128 bytes, 1 for 256, 2 for
512, etc.
The crc is a cyclic redundancy check of the data bits starting with
the mark just after the pulse train using polynom 0x11021.
The Western Digital-based controllers usually get rid of everything
but some 0xff before the first sector and allow a better use of space
as a result.
2.3.2.2 MFM sector layout
The standard "PC" track/sector layout for MFM is as such:
- A number of MFM-encoded 0x4e (usually 80)
- 12 FM-encoded 0x00 (giving a steady 250KHz pulse train)
- 3 times the 16-cell stream 0101001000100100 (5224, clock 0x14, data 0xc2)
- The MFM-encoded value 0xfc
- A number of MFM-encoded 0x4e (usually 50, very variable)
Then for each sector:
- 12 FM-encoded 0x00 (giving a steady 250KHz pulse train)
- 3 times the 16-cell stream 0100010010001001 (4489, clock 0x0a, data 0xa1)
- Sector header, e.g. MFM-encoded 0xfe, track, head, sector, size code and two bytes of crc
- 22 MFM-encoded 0x4e
- 12 MFM-encoded 0x00 (giving a steady 250KHz pulse train)
- 3 times the 16-cell stream 0100010010001001 (4489, clock 0x0a, data 0xa1)
- MFM-encoded 0xfb, sector data followed by two bytes of crc
- A number of MFM-encoded 0x4e (usually 84, very variable)
The track is finished with a stream of MFM-encoded 0x4e.
The 250KHz pulse trains are used to lock the PLL to the signal
correctly. The cell pattern 4489 does not appear in normal
MFM-encoded data and is used for clock/data separation.
As for FM, the Western Digital-based controllers usually get rid of
everything but some 0x4e before the first sector and allow a better
use of space as a result.
2.3.2.3 Formatting and write splices
To be usable, a floppy must have the sector headers and default sector
data written on every track before using it. The controller starts
writing at a given place, often the index pulse but on some systems
whenever the command is sent, and writes until a complete turn is
done. That's called formatting the floppy. At the point where the
writing stops there is a synchronization loss since there is no chance
the cell stream clock warps around perfectly. This brutal phase
change is called a write splice, specifically the track write splice.
It is the point where writing should start if one wants to raw copy
the track to a new floppy.
Similarly two write splices are created when a sector is written at
the start and end of the data block part. They're not supposed to
happen on a mastered disk though, even if there are some rare
exceptions.
3 The new implementation
3.1 Floppy disk representation
Th floppy disk contents are represented by the class floppy_image. It
contains information of the media type and a representation of the
magnetic state of the surface.
The media type is divided in two parts. The first half
indicates the physical form factor, i.e. all medias with that
form factor can be physically inserted in a reader that handles
it. The second half indicates the variants which are usually
detectable by the reader, such as density and number of sides.
Track data consists of a series of 32-bits lsb-first values
representing magnetic cells. Bits 0-27 indicate the absolute
position of the start of the cell (not the size), and bits
28-31 the type. Type can be:
- 0, MG_A -> Magnetic orientation A
- 1, MG_B -> Magnetic orientation B
- 2, MG_N -> Non-magnetized zone (neutral)
- 3, MG_D -> Damaged zone, reads as neutral but cannot be changed by writing
The position is in angular units of 1/200,000,000th of a turn. It
corresponds to one nanosecond when the drive rotates at 300 rpm.
The last cell implicit end position is of course 200,000,000.
Unformatted tracks are encoded as zero-size.
The "track splice" information indicates where to start writing
if you try to rewrite a physical disk with the data. Some
preservation formats encode that information, it is guessed for
others. The write track function of fdcs should set it. The
representation is the angular position relative to the index.
3.2 Converting to and from the internal representation
3.2.1 Class and interface
We need to be able to convert on-disk formats of the floppy data to
and from the internal representation. This is done through classes
derived from floppy_image_format_t. The interface to be implemented
includes:
- name() gives the short name of the on-disk format
- description() gives a short description of the format
- extensions() gives a comma-separated list of file name extensions
found for that format
- supports_save() returns true is converting to that external format
is supported
- identify(file, form factor) gives a 0-100 score for the file to be
of that format:
- 0 = not that format
- 100 = certainly that format
- 50 = format identified from file size only
- load(file, form factor, floppy_image) loads an image and converts it
into the internal representation
- save(file, floppy_image) (if implemented) converts from the internal
representation and saves an image
All these methods are supposed to be stateless.
3.2.2 Conversion helper methods
A number of methods are provided to simplify writing the converter
classes.
3.2.2.1 Load-oriented conversion methods
generate_track_from_bitstream(track number,
head number,
UINT8 *cell stream,
int cell count,
floppy image)
Takes a stream of cell types (0/1), MSB-first, converts it to the
internal format and stores it at the given track and head in the
given image.
generate_track_from_levels(track number,
head number,
UINT32 *cell levels,
int cell count,
splice position,
floppy image)
Takes a variant of the internal format where each value represents a
cell, the position part of the values is the size of the cell and
the level part is MG_0, MG_1 for normal cell types, MG_N, MG_D for
unformatted/damaged cells, and MG_W for Dungeon-Master style weak
bits. Converts it into the internal format. The sizes are
normalized so that they total to a full turn.
normalize_times(UINT32 *levels,
int level_count)
Takes an internal-format buffer where the position part represents
angle until the next change and turns it into a normal positional
stream, first ensuring that the total size is normalized to a full
turn.
3.2.2.2 Save-oriented conversion methods
generate_bitstream_from_track(track number,
head number,
base cell size,
UINT8 *cell stream,
int &cell_stream_size,
floppy image)
Extract a cell 0/1 stream from the internal format using a PLL setup
with an initial cell size set to 'base cell size' and a +/- 25%
tolerance.
struct desc_xs { int track, head, size; const UINT8 *data }
extract_sectors_from_bitstream_mfm_pc(...)
extract_sectors_from_bitstream_fm_pc(const UINT8 *cell stream,
int cell_stream_size,
desc_xs *sectors,
UINT8 *sectdata,
int sectdata_size)
Extract standard mfm or fm sectors from a regenerated
cell stream. Sectors must point to an array of 256 desc_xs.
An existing sector is recognizable by having ->data non-null.
Sector data is written in sectdata up to sectdata_size bytes.
get_geometry_mfm_pc(...)
get_geometry_fm_pc(floppy image,
base cell size,
int &track_count,
int &head_count,
int &sector_count)
Extract the geometry (heads, tracks, sectors) from a pc-ish floppy
image by checking track 20.
get_track_data_mfm_pc(...)
get_track_data_fm_pc(track number,
head number,
floppy image,
base cell size,
sector size,
sector count,
UINT8 *sector data)
Extract what you'd get by reading in order 'sector size'-sized
sectors from number 1 to sector count and put the result in sector
data.
3.3 Floppy drive
The class floppy_image_interface simulates the floppy drive. That
includes a number of control signals, reading, and writing. Control
signal changes must be synchronized, e.g. fired off a timer to ensure
the current time is the same for all devices.
3.3.1 Control signals
Due to the way they're usually connected to CPUs (e.g. directly on an
I/O port), the control signals work with physical instead of logical
values. Which means than in general 0 means active, 1 means inactive.
Some signals also have a callback associated called when they change.
mon_w(state) / mon_r()
Motor on signal, rotates on 0.
idx_r() / setup_index_pulse_cb(cb)
Index signal, goes 0 at start of track for about 2ms. Callback is
synchronized. Only happens when a disk is in and the motor is
running.
ready_r() / setup_ready_cb(cb)
Ready signal, goes to 1 when the disk is removed or the motor
stopped. Goes to 0 after two index pulses.
wpt_r() / setup_wpt_cb(cb)
Write protect signal (1 = readonly). Callback is unsynchronized.
dskchg_r()
Disk change signal, goes to 1 when a disk is change, goes to 0 on
track change.
dir_w(dir)
Selects track stepping direction (1 = out = decrease track number).
stp_w(state)
Step signal, moves by one track on 1->0 transistion.
trk00_r()
Track 0 sensor, returns 0 when on track 0.
ss_w(ss) / ss_r()
Side select
3.3.2 Read/write interface
The read/write interface is designed to work asynchronously,
e.g. somewhat independently of the current time.
[1] Cylinder is a hard-drive term somewhat improperly used for
floppies. It comes from the fact that hard-drives are similar to
floppies but include a series of stacked disks with a read/write head
on each. The heads are physically linked and all point to the same
circle on every disk at a given time, making the accessed area look
like a cylinder. Hence the name.

131
docs/hlsl.txt
View File

@ -1,131 +0,0 @@
HLSL-Related Enable Switches
----------------------------
Name Values Description
hlsl_enable 0 or 1 Enables HLSL post-processing in Direct3D 9 modes.
hlsl_oversampling 0 or 1 Enables HLSL oversampling.
yiq_enable 0 or 1 Enables YIQ-colorspace post-processing. Causes a
performance drop but gives a much more authentic
NTSC TV appearance on TV-based systems when configured
properly.
hlslpath [path] Path to the .fx files that are in use. (default: hlsl)
hlsl_write [filename] Enables HLSL AVI writing. (huge disk bandwidth suggested)
hlsl_snap_width [width] HLSL upscaled-snapshot width. (default: 2048)
hlsl_snap_height [height] HLSL upscaled-snapshot height. (default: 1536)
Surface/Color Processing Parameters
-----------------------------------
Name Values Description
shadow_mask_tile_mode 0 or 1 0 for screen based tile mode or 1 for source based tile mode.
shadow_mask_alpha 0.0 to 1.0 The ovearll darkness of each shadow mask pixel.
shadow_mask_texture [filename] A PNG that defines the shadow mask for each pixel.
shadow_mask_x_count 1+ The number of pixels one shadow mask tile uses on screen.
shadow_mask_y_count 1+ This stretches the shadow mask tiles on X and Y axis.
shadow_mask_usize 0.0 to 1.0 The size of one shadow mask tile in U/V coordinate.
shadow_mask_vsize 0.0 to 1.0 The shadow mask textures always has a size of power-of-two.
shadow_mask_voffset -1.0 to 1.0 The offset of the shadow mask texture in U/V coordinates.
shadow_mask_voffset -1.0 to 1.0 An offset of 1.0 repressents one pixel on screen.
distortion -1.0 to 1.0 Distortion amount of the screen.
cubic_distortion -1.0 to 1.0 Cubic Distortion amount of the screen.
distort_corner 0.0 to 1.0 Distorted corners amount of the screen.
round_corner 0.0 to 1.0 Rounded corners amount of the screen.
smooth_border 0.0 to 1.0 Smooth borders amount of the screen.
reflection 0.0 to 1.0 Refelection amount of the screen highlight.
vignetting 0.0 to 1.0 Vignetting amount of the image.
scanline_alpha 0.0 to 1.0 The overall darkness of each scanline furrow.
scanline_size 0.0 to 4.0 The overall height of each scanline.
scanline_height [height] Individual height scaling value for scanlines.
scanline_bright_scale 0.0 to 2.0 The overall brightness multiplier for each scanline.
scanline_bright_offset 0.0 to 1.0 The overall brightness additive value for each scanline.
scanline_jitter 0.0 to 1.0 The relative scanline movement per field.
hum_bar_alpha 0.0 to 1.0 The maximum darkness of the hum bar gradient.
defocus [xval,yval] This defines the overall defocus radius for the three
post-converged beams. Values allowed range from 0.0 to
10.0.
converge_x [r,g,b] Convergence in screen-relative X direction.
converge_y [r,g,b] Convergence in screen-relative Y direction.
radial_converge_x [r,g,b] Radial convergence in screen-relative X direction.
radial_converge_y [r,g,b] Radial convergence in screen-relative Y direction.
Allowed values for convergence: -10.0 to 10.0 for each color.
red_ratio [r,g,b] These parameters define a 3x3 matrix which is multiplied
grn_ratio [r,g,b] by the incoming RGB signal. This can be used for any
blu_ratio [r,g,b] standard matrix convolution, including H/S/V or simply
affecting the TV-style tint.
saturation 0.0 to 4.0 This parameter defines the amount each color channel is
raised above said channel's baseline grayscale value.
A value of 0.0 gives a gamma-correct grayscale image,
whereas 1.0 is full saturation, with each channel being
oversaturated equally beyond that.
offset [r,g,b] These parameters define a value for each color channel
that is added to said channel after scaling and after
matrix convolution. (-2.0 to 2.0)
scale [r,g,b] These parameters define a value for each color channel
that is multiplied with said channel after matrix
convolution. (-2.0 to 2.0)
power [r,g,b] These parameters define the exponent for each color
channel that is applied after scaling, offsetting,
saturation and matrix convolution. (-4.0 to 4.0)
floor [r,g,b] These parameters define the lower limit of each final
color channel value; 0.05, for example, raises the
minimum to 0.05 but re-scales to leave the max at 1.0.
phosphor_life [r,g,b] These parameters define the phosphor lifetime for each
channel, with 0.0 representing no phosphorescence and
1.0 leaving the channel on indefinitely. Values allowed
range from 0.0 to 1.0.
NTSC Processing Parameters
--------------------------
Name Default Values Description
yiq_jitter 0.0 Jitter for the NTSC signal processing. (0.0 to 1.0)
yiq_cc 3.57954545 Color Carrier frequency for NTSC signal processing. (0.0 to 6.0)
yiq_a 0.5 A value for NTSC signal processing. (-1.0 to 1.0)
yiq_b 0.5 B value for NTSC signal processing. (-1.0 to 1.0)
yiq_o 0.0 Outgoing Color Carrier phase offset for NTSC signal processing. (-3.0 to 3.0)
yiq_p 1.0 Incoming Pixel Clock scaling value for NTSC signal processing. (-3.0 to 3.0)
yiq_n 1.0 Y filter notch width for NTSC signal processing. (0.0 to 6.0)
yiq_y 6.0 Y filter cutoff frequency for NTSC signal processing. (0.0 to 6.0)
yiq_i 1.2 I filter cutoff frequency for NTSC signal processing. (0.0 to 6.0)
yiq_q 0.6 Q filter cutoff frequency for NTSC signal processing. (0.0 to 6.0)
yiq_scan_time 52.6 Horizontal scanline duration for NTSC signal processing. (usec)
yiq_phase_count 2 Phase Count value for NTSC signal processing. (3 for NES, else 2)
Vector Post-Processing Options
------------------------------
Name Default Values Description
vector_beam_smooth 0.0 The vector beam smoothness. (0.00 to 1.00)
vector_length_scale 0.5 The maximum vector attenuation. (0.00 to 1.00)
vector_length_ratio 0.5 The minimum vector length (vector length to screen size ratio)
that is affected by the attenuation (0.000 to 1.000)
Bloom Post-Processing Options
-----------------------------
Name Default Values Description
bloom_blend_mode 0 or 1 0 for brighten blend mode or 1 for darken blend mode.
bloom_scale 0.0 Bloom intensity factor. (0.000 to 2.000)
bloom_overdrive 0.0,0.0,0.0 Bloom overdrive factor to bright full saturated colors. (0.000 to 2.000)
bloom_lvl0_weight 1.00 Bloom level 0 weight. (full-size target) (0.00 to 1.00)
bloom_lvl1_weight 0.64 Bloom level 1 weight. (1/4 smaller that level 0 target) (0.00 to 1.00)
bloom_lvl2_weight 0.32 Bloom level 2 weight. (1/4 smaller that level 1 target) (0.00 to 1.00)
bloom_lvl3_weight 0.16 Bloom level 3 weight. (1/4 smaller that level 2 target) (0.00 to 1.00)
bloom_lvl4_weight 0.08 Bloom level 4 weight. (1/4 smaller that level 3 target) (0.00 to 1.00)
bloom_lvl5_weight 0.06 Bloom level 5 weight. (1/4 smaller that level 4 target) (0.00 to 1.00)
bloom_lvl6_weight 0.04 Bloom level 6 weight. (1/4 smaller that level 5 target) (0.00 to 1.00)
bloom_lvl7_weight 0.02 Bloom level 7 weight. (1/4 smaller that level 6 target) (0.00 to 1.00)
bloom_lvl8_weight 0.01 Bloom level 8 weight. (1/4 smaller that level 7 target) (0.00 to 1.00)
Presets
-------
../ini/presets/raster.ini for raster screens
../ini/presets/vector.ini for color vector screens
../ini/presets/vector-mono.ini for monochrome vector screens (rename to vector.ini or <system>.ini)
../ini/presets/lcd.ini for screens with TFT color LCD
../ini/presets/lcd-matrix.ini for screens with STN LCD matrix (rename to lcd.ini or <system>.ini)
../ini/presets/gameboy.ini for Game Boy screen (same as lcd-matrix.ini with greenish color transformation)
../ini/presets/gba.ini for Game Boy Advance screen (same as lcd.ini)

577
docs/imgtool.txt
View File

@ -1,577 +0,0 @@
Imgtool - A generic image manipulation tool for MESS
Imgtool is a tool for the maintenance and manipulation of disk and other types
of images that MESS users need to deal with. Functions include retrieving and
storing files and CRC checking/validation.
Imgtool is part of the MESS project. It shares large portions of code with
MESS/MAME, and its existence would not be if it were not for MESS. As such,
the distribution terms are the same as MESS. Please read mess.txt thoroughly.
Some portions in Imgtool is Copyright (c) 1989, 1993 The Regents of the
University of California. All rights reserved.
Using Imgtool
=============
Imgtool is a command line program that contains several "subcommands" that
actually do all of the work. Most commands are invoked in a manner along the
lines of this:
imgtool <subcommand> <format> <image> ...
<subcommand> is the name of the subcommand
<format> is the format of the image
<image> is the filename of the image
Further details vary with each subcommand. Also note that not all subcommands
are applicable or supported for different image formats.
Certain Imgtool subcommands (info, crc, good) make use of the CRC files, so if
you use these commands, make sure that your CRC directory is set up.
Imgtool Subcommands
===================
create Creates an image
dir Lists the contents of an image
get Gets a single file from an image
put Puts a single file on an image (wildcards supported)
getall Gets all files off an image
del Deletes a file on an image
info Retrieves info about an image (by reading CRC files)
crc Retrieves info about an image in the same format used by the
CRC files
good CRC checks a set of images and for matching images, copy into
a new directory
listformats Lists all image file formats supported by imgtool
listfilters Lists all filters supported by imgtool
listdriveroptions Lists all format-specific options for the 'put' and 'create'
commands
Filters
=======
Filters are a means to process data being written into or read out of an image
in a certain way. Filters can be specified on the get, put, and getall
commands by specifying --filter=xxxx on the command line. Currently, only
three filters are supported:
ascii Translates end-of-lines to the appropriate format
cocobas Processes tokenized CoCo BASIC programs
dragonbas Processes tokenized Dragon BASIC programs
Format Info
===========
rsdos CoCo Disks
----------------
Fully implemented. This format supports two format-specific options on the put
command:
--ftype=(basic|data|binary|assembler) Specifies the file type
--ascii=(ascii|binary) Specifies the ASCII flag
cococas CoCo Cassettes
----------------------
Both .cas and .wav supported, but read only.
lnx Commodore 64 Lynx Archive
-----------------------------
only for early revisions of lynx archivs
only extraction supported
not heavily tested
Lynx archivs could and should be handled in a c64 emulation
with the native lynx tool
t64 Commodore 64/C64S Archive for Tapes
---------------------------------------
not heavily tested
further creation/use of these archivs discouraged
c64crt/crt Commodore 64 Cartridge
---------------------------------
for professional use only (cartridge dumper)
not heavily tested
d64 Commodore SX64/VC1541/1551/2031 Diskette
x64 VICE variant of the above
d71 Commodore 128D/1571 Diskette
d81 Commodore 65/1565/1581 Diskette
-----------------------------------
not heavily tested
x64: further creation/use discouraged
msdos/fat Microsoft DOS Diskette
--------------------------------
directories not finished
not heavily tested
Formatting (low and high level) must be done with the msdos utility format!
Boot structures must be installed on these disks with the msdos utility sys!
standard parameter for common disk formats:
type 0: 5 1/4 inch, double density, single sided, 160kb: sectors 8, heads 1, tracks 40
type 1: 5 1/4 inch, DD, SS, 180kb: sectors 9, heads 1, tracks 40
type 2: 5 1/4 inch, DD, double sided, 320kb: sectors 8, heads 2, tracks 40
type 3: 5 1/4 inch, DD, DS, 360kb: sectors 9, heads 2, tracks 40
type 4: 3 1/2 inch, DD, DS, 720kb: sectors 9, heads 2, tracks 80
at disk controller necessary for high density
type 5: 5 1/4 inch, high density, DS, 1.2mb: sectors 15, heads 2, tracks 80
3 1/2 inch, HD, DS, 1.2mb: sectors 15, heads 2, tracks 80
type 6: 3 1/2 inch, HD, DS, 1.44mb: sectors 18, heads 2, tracks 80
special disk controller necessary for enhanced density
type 7: 3 1/2 inch, enhanced density, DS, 2.88mb: sectors 36, heads 2, tracks 80
unix with bash: use
dd if=/dev/zero of=<name.dsk> bs=512 count=$((9*2*40))
to generate standard blank 360kb image
msdoshd/fat Microsoft DOS Harddisk/PC Partition Table
-----------------------------------------------------
not finished and not working
(see also unter msdos/fat)
No low level format necessary with image files
Partitioning must be done with the msdos utility fdisk
Then you can format each partition with msdos utility format
standard parameter for common disk formats:
type 0: 20mb standard pc/xt harddisk: 17 sectors, 4 heads, 615 cylinders
unix with bash: use
dd if=/dev/zero of=<name.dsk> bs=512 count=$((17*4*615))
to generate standard blank 20mb pc xt harddisk image
Virtual MSX tape archive
------------------------
Converts .tap files from Virtual MSX 1.x to .cas files. It is not
fault-tolerant.
Virtual MSX Game Master 2 SRAM file
-----------------------------------
Very simple, not overly useful but some might want it. Virtual MSX stored the
SRAM of Konami's Game Master 2 in "gmaster2.ram". To convert this to something
useful with MESS and other MSX emulators, go:
imgtool getall vmsx_gm2 gmaster2.ram
You'll get a file called gmaster2.mem, which must place in the correct directory
of mess to use (MESS\MEMCARD\GameMaster2 if your Game Master 2 .rom file is
called GameMaster2.rom). It's ~/.xmess/memcard/GameMaster2.mem for xmess.
fMSX style .cas file
--------------------
Converts .cas files to .wav files. The MSX driver can use .cas files directly
so you don't have to convert them. You can use it to export files to a real
MSX. Connect the MSX to the line out of your computer. Give the apropriate
command on the MSX (BLOAD "CAS:",R for example) and then play the .wav file
on your computer.
imgtool dir fmsx_cas file.cas
imgtool getall fmsx_cas file.cas
imgtool get fmsx_cas file.cas file.wav newfile.wav
XelaSoft Archive (.xsa)
-----------------------
The XelaSoft Archive is a compressed file. It can only contain one
file. Although it can contain any file, it's always used for MSX disk
images. The were programs written by XelaSoft which made a dump
of a disk, and compressing them at the same time. Very useful to store
a disk dump on another disk. zip/gzip offer much better compression and
are mainstream, so let's stick with that.
imgtool uses XSA code developed by Alex Wulms/XelaSoft.
http://web.inter.nl.net/users/A.P.Wulms/
Various bogus MSX disk images (img/ddi/msx/multidisks)
------------------------------------------------------
These are formats you might come across, which have no actual added value
whatsoever. The only format MESS will support, like most other MSX
emulators, is .dsk (a plain dump without any header information). This
filetype converts them all to .dsk format.
msx_img are disk images with an extra byte at the beginning. It' 1 (0x01)
for single-sided images and 2 (0x02) for double-side images. These
files are at: ftp://ftp.funet.fi/pub/msx/. The extension is .img
msx_ddi are DiskDupe 5.12 disk images. There is a 0x1800 bytes header
at the beginning. The CompuJunkS MSX emulator used these files. The header
often contain garbage so it's simply stripped. The extension is .ddi
msx_msx are disk images with a weird sector order. You can find them
at: ftp://jazz.snu.ac.kr/pub/msx/. The extension is .msx
msx_mul are "multi disk" images, used by fmsx-dos 1.6. It is simply
more than one .dsk image appended to one another. The extension is
still .dsk, but the file is larger than 720kB (actually always a
multiple of 720kB.
rom16 16 bit wide rom image
---------------------------
allows easy access to even and odd parts
file even: even bytes
file odd: odd bytes
Amstrad NC100/NC150/NC200 PCMCIA Ram Card Images (crd/card)
-----------------------------------------------------------
The card filesystem is similar to FAT, but not identical.
The maximum card size is 1mb, and maximum file size is 64k.
(Files will be cut at 64k if they are larger - e.g. when putting a large file)
As far as I know there is no directory system, however there is always a
system "NC100" directory which points to the root directory. (Like the DOS "."
directory).
Using imgtool, you can put, get and delete files.
At this time only ascii file type is supported. These files can be loaded
into the internal wordprocessor,or,if the file is a BASIC listing, it can
be loaded into basic with "*EXEC <filename>" at the ">" prompt.
From BASIC you can get a directory listing of the card filesystem with "*."
at the ">" prompt.
The file date information is not supported at this time.
The card filesystem reading/writing in imgtool has not been heavily tested.
TI99 floppy disk images (v9t9/pc99fm/pc99mfm/ti99_old)
------------------------------------------------------
These modules enable you to create and catalog ti99 images, to delete
individual files and directories, and to get and put files in TIFILE format.
Note that you cannot create images in pc99 format.
The v9t9 module supports the v9t9 disk images that is used by MESS, the pc99fm
module supports FM-encoded pc99 images, and the pc99mfm supports MFM-encoded
pc99 images, and the ti99_old module supports the now obsolete image format
that was used by MESS versions prior to .69. The MESS ti99 drivers supports
the v9t9 disk image format only. (Note that the old MESS format was identical
to the V9T9 format for single-sided disks, but that the track order was
completely different for double-sided disks, which caused the two formats to be
incompatible for double-sided disk images. I have changed the format to v9t9
as this format is used by most other TI99 utilities and emulators.)
The TIFILE format is a file format that is supported by many ti99 utilities: it
encodes a TI99 file as a flat stream of bytes, which enables to store it on
file systems that do not support the TI99 file structure and to transmit it
through networks. This format uses a data format similar to the one used on
ti99 floppies (i.e. logical records are grouped in physical records of 256
bytes), with a custom 128-byte header.
Legal characters for volume and file names are upper case ASCII characters,
except period ('.') and space (' '). Lower case characters are not recommended
because they are not supported by TI99/4. You had better avoid control
characters and non-ASCII characters, too. (Additionally, the NULL character is
forbidden in file names, but I think nobody in his right sense would even try
to enter a NULL character in a file name.) The restriction on the period ('.')
character may sound strange to users of other OSes, but this character is used
as a path separator by TI systems. (As a matter of fact, no TI99 floppy disk
DSR (except the HFDC DSR) implements disk directories, but other TI systems
implement this convention extensively.) Since period is used as the path
separator, TI99 users often use the slash ('/') or dash ('-') characters as
file extension separators; note, however, that the use of file extensions is
never systematic in TI99: you may use file extensions if you find them useful,
just like you may use any other file naming scheme, but no program enforce or
require filename extensions as it is often the case in the DOS/windows world.
Parameters for create:
--label=...: an optional string of up to 10 characters.
--sides=[1|2]: 1 for single-sided, 2 for double-sided.
--tracks=[1-80]: number of track per side. Should be 40 for a 40-track disk,
and 80 for an 80-track disk.
--sectors=[1-36]: number of sectors per track. Should be 9 in single density
(FM), 18 in double density (MFM), and 36 in high density (MFM).
--protection=[0|1]: when set to 1, the disk will be protected and some (but not
all) TI99 programs won't overwrite the disk.
--density=[Auto|SD|DD|HD]: you should probably leave this parameter to Auto, so
that imgtool picks the correct value automatically (according to the number
of sectors per track). If you really need to, SD forces single density
(FM), DD forces double density (MFM), and HD forces high density (MFM).
Supported geometries for create:
description |sides|tracks|sectors| size | FDC Compatibility (1)
| | | | |
SSSD 48TPI 5"1/4 | 1 | 40 | 9 | 90K | All
| | | | |
DSSD 48TPI 5"1/4 | 2 | 40 | 9 | 180K | All
| | | | |
DSDD 48TPI 5"1/4 | 2 | 40 | 18 | 360K | SNUG BwG, Myarc HFDC
| | | | |
DSDD 96TPI 5"1/4 | 2 | 80 | 18 | 720K | Myarc HFDC (2)
or DSDD 3"1/2 | | | | |
| | | | |
DSHD 3"1/2 | 2 | 80 | 36 |1.44M | Myarc HFDC (Geneve Only) (3)
(1) Only emulated controllers are listed in this table
(2) SNUG BwG can read such images, but it will corrupt them when writing new
data to them
(3) You cannot boot from such images (this is because the Geneve MDOS operating
system needs to replaces the incomplete HFDC DSR with a better DSR to
support HD: since MDOS is not loaded yet at boot time, you cannot boot from
a HD disk).
Examples:
List the catalog of image test.dsk:
imgtool dir v9t9 test.dsk
Extract file FILE1 located on image test.dsk:
imgtool get v9t9 test.dsk FILE1
Extract file FILE1 located in subdirectory SUBDIR1 on image test.dsk:
imgtool get v9t9 test.dsk SUBDIR1.FILE1
Write file FILE1 on image test.dsk:
imgtool put v9t9 test.dsk FILE1
(Note that file FILE1 must not exist before the command is run. Use the delete
command first if you need to overwrite an existing file.)
Delete file FILE1 located in subdirectory SUBDIR1 on image test.dsk:
imgtool delete v9t9 test.dsk SUBDIR1.FILE1
Delete subdirectory SUBDIR1 on image test.dsk:
imgtool delete v9t9 test.dsk SUBDIR1
(Subdirectory SUBDIR1 must be empty.)
Create a SSSD image compatible with all controllers:
imgtool create v9t9 test.dsk --sides=1 --tracks=40 --sectors=9
Create a DSSD image compatible with all controllers:
imgtool create v9t9 test.dsk --sides=2 --tracks=40 --sectors=9
Create a DSDD image compatible with BwG and HFDC controllers:
imgtool create v9t9 test.dsk --sides=2 --tracks=40 --sectors=18
Create a 80-track DSDD image compatible with the HFDC controller:
imgtool create v9t9 test.dsk --sides=2 --tracks=80 --sectors=18
Create a DSHD image compatible with the Geneve with a HFDC controller:
imgtool create v9t9 test.dsk --sides=2 --tracks=80 --sectors=36
TI99 hard disk images (ti99hd)
------------------------------
This module can catalog ti99 hard disk images, delete individual files and
directories, and get and put files in TIFILE format. Only images in HFDC
format are supported for now (no SCSI format).
TI990 disk images (ti990hd)
---------------------------
This module supports disk images in DNOS format (which appears to be virtually
identical to DX10 3.x format). Although the module is named ti990hd, this
module will work fine with floppy images as well as hard disk images: just make
sure that the disks are formatted in the proper format, as neither DX10 2.x nor
TX990 formats are supported.
Parameters for create:
The most interesting command is create, as you cannot create new images within
emulation.
--cylinders: number of cylinders
--heads: number of heads
--sectors: number of sectors per track
--seclen: bytes per sector
Known restrictions on geometry:
256 < bytes per sector < 512 (arbitrary restriction, actual TI990s might
accept values out of this range)
bytes per sector must be even
3 < # cylinders < 2047
1 < # heads < 31
1 < sectors per track < 256
(sectors per track) * (bytes per sector) < 2^17 = 131072 (which implies
(sectors per track) < 255 if sectors are 512-byte long)
(There are probably other restrictions, so you had better stick to values
similar to the ones used by actual disk units... Also note that according to
the Spectra 126-Plus manual, ADU size limitations prevent most operating
systems from supporting units larger than 500MBytes.)
Known drive geometries:
(Sources: 946250-9703 p. 3-14, 2270512-9701 p. 11-3, 945250-9701 pp. 5-20
through 5-28, 946250-9701B pp. 2-1 through 2-3, 2540219A-0001 pp. 4-2 and 4-3,
2306140-9701 p. 1-15, 223439B-9701 pp. 3-14 and 3-28. See also "Spectra
126-Plus Product Reference Manual" by Cipher P/N 8500055 revision A4 page 2-8.)
Disk Type Units Size (MB) Cylinders Heads Sectors/Track Bytes/Sector
FD800 (min) 1 .244 77 1 26 128
FD800 (max) 1 .978??? 77 2??? 26??? 256???
FD1000 1 1.15 77 2 26 288
DS31/DS32 1 2.81 203 2 24 288
DS10 2 4.70 408 2(*2) 20 288
DS25 1 22.3 408 5 38 288
DS50 1 44.6 815 5 38 288
DS200 1 169.5 815 19 38 288
CD1400-32 2 13.5 821(h) 1 64 256
CD1400-64 (rem) 1 13.5 821(h) 1 64 256
CD1400-64 (fix) 1 38.5 821(h) 3 64 256
CD1400-96 (rem) 1 13.5 821(h) 1 64 256
CD1400-96 (fix) 1 67.3 821(h) 5 64 256
DS80 1 62.7 803(g) 5 61 256
DS300 1 238.3 803(c) 19 61 256
WD800-18 1 18.5 651(b) 3 37 256
WD800-43 1 43.2 651(b) 7 37 256
WD800A/38 1 38.5 911(d) 5 33 256
WD800A/69 1 69.3 911(d) 9 33 256
WD800A/114 1 114.6 904(d) 15 33 256
WD500 1 4.92 150(a) 4 32 256
WD500A 1 17.1 694(a) 3 32 256
WD900-138 1 138.1 805(e) 10 67 256
WD900-138/2 2 69.0 805(e) 5(*2) 67 256
WD900-425 1 425.8 693(e) 24 100 256
WD900-425/2 2 212.9 693(e) 12(*2) 100 256
MSU II 1 158.8 957(f) 9 36 512
MSU IIA 1 332.9 1204(f) 15 36 512
a) some extra cylinders are reserved for diagnostics
b) 6 extra cylinders are reserved for storage system use (including 2 for
diagnostics)
c) some extra cylinders are reserved for diagnostics, and 10 extra cylinders
are reserved to replace bad tracks
d) 4 extra cylinders are reserved for storage system use (including 2 for
diagnostics), and 10 extra cylinders are reserved to replace bad tracks
e) 16 extra cylinders are reserved for bad track relocation
f) there are extra cylinders, and the way logical addresses relates to physical
address is so complex I don't even want to talk about it
g) 2 extra cylinders are reserved for diagnostics, and 10 extra cylinders are
reserved to replace bad tracks
h) 2 extra cylinders are reserved for diagnostics
Note that 2270512-9701 and 946250-9703 describe more disk units (namely CMD 16,
CMD 80, WD800A-43 and WD800A-100 for the former, and WD500-10 for the later).
Since there are no other references anywhere and DX-10 does not seem to know
about them, I assume that these models were uncommon.
FD800 is a 8" floppy disc unit that is not emulated, and it is only cited for
completeness. (The FD800 controller is connected to the CRU bus instead of the
TILINE bus, and it is the only disc controller that is supported by non-TILINE
systems).
FD1000 is a 8" floppy disc unit.
DS31/DS32 was the first hard disk unit for ti990. The only difference between
DS31 and DS32 is that DS32 does not require a screwdriver to change the disc
cartridge.
DS10 has one 5-mb fixed platter and one 5mb disk cartridge.
CD1400-32 and CD1400-96 have a one-platter 16-mb removable unit, and a fixed
unit (16 mb for CD1400-32 and 80 mb for CD1400-96).
WDxxx units are Winchester drives that connect to a proprietary PBUS bus
interface. This bus is a built-in interface in BS300 and BS300A systems, and
the TPBI card enables any TILINE 990 system to support it. WD800s are 8"
drives with integrated tape backup, WD500s are 5"1/4 drives with integrated
FD1000 backup, and WD900s are 9" drives. The WD900 controller can optionally
partition the disc into two partitions: the set-up with no partitioning is
listed as WD900-138 and WD900-425, whereas the set-up with partitioning is
listed as WD900-138/2 and WD900-425/2.
MSU II and MSU IIa are SCSI units to be connected to the 990/SCSI controller
board.
Macintosh floppy disk images (mac)
----------------------------------
This module supports MFS (Macintosh File System) and HFS (Hierarchical File
System) floppy disk images, either in diskcopy 4.2 or raw image format (the raw
image format is partially compatible with diskcopy 6 format).
This module can catalog images, and get files in MacBinary format. You can put
files on MFS-formatted images, too, but not on HFS-formatted images.
The module does not support folders in MFS format, because MFS folders are not
documented by Apple.
Extracted files are in MacBinary III format (which is fully compatible with
MacBinary I and II). The MacBinary III format joins both macintosh file forks,
the comment field, and most file info in one single file: it is supported by
several Macintosh utilities.
Texas Instruments calculators variable files
--------------------------------------------
+--------+------------------------------------------+-----------+
| Format | Description | Extension |
+--------+------------------------------------------+-----------+
| ti85p | TI-85 program file | 85p |
| ti85s | TI-85 string file (also ZShell programs) | 85s |
| ti85i | TI-85 picture file (85-image) | 85i |
| ti85n | TI-85 real number file | 85n |
| ti85c | TI-85 complex number file | 85c |
| ti85l | TI-85 list (real or complex) | 85l |
| ti85k | TI-85 constant file | 85k |
| ti85m | TI-85 matrix (real or complex) file | 85m |
| ti85v | TI-85 vector (real or complex) file | 85v |
| ti85d | TI-85 graphics database file | 85d |
| ti85e | TI-85 equation file | 85e |
| ti85r | TI-85 range settings file | 85r |
| ti85g | TI-85 grouped file | 85g |
| ti85 | TI-85 generic file | 85? |
| ti86p | TI-86 program file | 86p |
| ti86s | TI-86 string file | 86s |
| ti86i | TI-86 picture file (85-image) | 86i |
| ti86n | TI-86 real number file | 86n |
| ti86c | TI-86 complex number file | 86c |
| ti86l | TI-86 list (real or complex) file | 86l |
| ti86k | TI-86 constant file | 86k |
| ti86m | TI-86 matrix (real or complex) file | 86m |
| ti86v | TI-86 vector (real or complex) file | 86v |
| ti86d | TI-86 graphics database file | 86d |
| ti86e | TI-86 equation file | 86e |
| ti86r | TI-86 range settings file | 86r |
| ti86g | TI-86 grouped file | 86g |
| ti86 | TI-86 generic file | 86? |
+--------+------------------------------------------+-----------+
Grouped formats (ti85g and ti86g) can keep more than one variable.
Generic formats (ti85 and ti86) can be used for all types of variable files.
For all types of variable files dir, create, put, get and delete commands are
supported.
Texas Instruments calculators memory backup files
-------------------------------------------------
+--------+------------------------------------------+-----------+
| Format | Description | Extension |
+--------+------------------------------------------+-----------+
| ti85b | TI-85 memory backup file | 85b |
+--------+------------------------------------------+-----------+
For TI memory backup files only dir command is supported.

190
docs/luaengine.md
View File

@ -1,190 +0,0 @@
# Scripting MAME via LUA
## Introduction
It is now possible to externally drive MAME via LUA scripts.
This feature initially appeared in version 0.148, when a minimal `luaengine`
was implemented. Nowadays, the LUA interface is rich enough
to let you inspect and manipulate devices state, access CPU
registers, read and write memory, and draw a custom HUD on screen.
Internally, MAME makes extensive use of `luabridge` to implement
this feature: the idea is to transparently expose as many of
the useful internals as possible.
Finally, a warning: LUA API is not yet declared stable and may
suddenly change without prior notice.
However, we expose methods to let you know at runtime which API
version you are running against, and you can introspect most of the
objects at runtime.
## Features
The API is not yet complete, but this is a partial list of capabilities
currently available to LUA scripts:
* machine metadata (app version, current rom, rom details)
* machine control (starting, pausing, resetting, stopping)
* machine hooks (on frame painting and on user events)
* machine options (hard reset required for options to take affect)
* devices introspection (device tree listing, memory and register enumeration)
* screens introspection (screens listing, screen details, frames counting)
* screen snaps and HUD drawing (text, lines, boxes on multiple screens)
* memory read/write (8/16/32/64 bits, signed and unsigned)
* registers and states control (states enumeration, get and set)
## Usage
MAME supports external scripting via LUA (>= 5.3) scripts, either
written on the interactive console or loaded as a file.
To reach the console, just run MAME with `-console`; you will be
greeted by a naked `>` prompt where you can input your script.
To load a whole script at once, store it in a plaintext file and
pass it via the `-autoboot_script`. Please note that script
loading may be delayed (few seconds by default), but you can
override the default with the `-autoboot_delay` argument.
To control the execution of your code, you can use a loop-based or
an event-based approach. The former is not encouraged as it is
resource-intensive and makes control flow unnecessarily complex.
Instead, we suggest to register custom hooks to be invoked on specific
events (eg. at each frame rendering).
## Walktrough
Let's first run MAME in a terminal to reach the LUA console:
```
$ mame -console YOUR_ROM
M.A.M.E. v0.158 (Feb 5 2015) - Multiple Arcade Machine Emulator
Copyright Nicola Salmoria and the MAME team
Lua 5.3.0 Copyright (C) 1994-2015 Lua.org, PUC-Rio
>
```
At this point, your game is probably running in demo mode, let's pause it:
```
> emu.pause()
>
```
Even without textual feedback on the console, you'll notice the game is now paused.
In general, commands are quiet and only print back error messages.
You can check at runtime which version of MAME you are running, with:
```
> print(emu.app_name() .. " " .. emu.app_version())
mame 0.158
```
We now start exploring screen related methods. First, let's enumerate available screens:
```
> for i,v in pairs(manager:machine().screens) do print(i) end
:screen
```
`manager:machine()` is the root object of your currently running machine:
we will be using this often. `screens` is a table with all available screens;
most machines only have one main screen.
In our case, the main and only screen is tagged as `:screen`, and we can further
inspect it:
```
> -- let's define a shorthand for the main screen
> s = manager:machine().screens[":screen"]
> print(s:width() .. "x" .. s:height())
320x224
```
We have several methods to draw on the screen a HUD composed of lines, boxes and text:
```
> -- we define a HUD-drawing function, and then call it
> function draw_hud()
>> s:draw_text(40, 40, "foo"); -- (x0, y0, msg)
>> s:draw_box(20, 20, 80, 80, 0, 0xff00ffff); -- (x0, y0, x1, y1, fill-color, line-color)
>> s:draw_line(20, 20, 80, 80, 0xff00ffff); -- (x0, y0, x1, y1, line-color)
>> end
> draw_hud();
```
This will draw some useless art on the screen. However, when unpausing the game, your HUD
needs to be refreshed otherwise it will just disappear. In order to do this, you have to register
your hook to be called on every frame repaint:
```
> emu.sethook(draw_hud, "frame")
```
All colors are expected in ARGB format (32b unsigned), while screen origin (0,0)
normally corresponds to the top-left corner.
Similarly to screens, you can inspect all the devices attached to a
machine:
```
> for k,v in pairs(manager:machine().devices) do print(k) end
:audiocpu
:maincpu
:saveram
:screen
:palette
[...]
```
On some of them, you can also inspect and manipulate memory and state:
```
> cpu = manager:machine().devices[":maincpu"]
> -- enumerate, read and write state registers
> for k,v in pairs(cpu.state) do print(k) end
D5
SP
A4
A3
D0
PC
[...]
> print(cpu.state["D0"].value)
303
> cpu.state["D0"].value = 255
> print(cpu.state["D0"].value)
255
```
```
> -- inspect memory
> for k,v in pairs(cpu.spaces) do print(k) end
program
> mem = cpu.spaces["program"]
> print(mem:read_i8(0xC000))
41
```
manager:options()
manager:machine():options()
manager:machine():ui():options()
```
> opts = manager:machine():options()
> for k, entry in pairs(opts.entries) do print(string.format("%10s: %s\n%11s %s", k, entry:value(), "", entry:description())) end
diff_directory: diff
directory to save hard drive image differeVnce files
joystick_contradictory: false
enable contradictory direction digital joystick input at the same time
scalemode: none
Scale mode: none, hwblit, hwbest, yv12, yuy2, yv12x2, yuy2x2 (-video soft only)
oslog: false
output error.log data to the system debugger
[...]
> print(opts.entries["sleep"]:value())
true
> print(opts.entries["sleep"]:value("invalid"))
Illegal boolean value for sleep: "invalid"; reverting to 1
true
> print(opts.entries["sleep"]:value(false))
false
```
individual screen snapshots
```
> local screen = manager:machine().screens[":screen"]
> screen:snapshot()
saved snap/gridlee/0000.png
> screen:snapshot('%g.png')
saved snap/gridlee.png
```

482
docs/m6502.txt
View File

@ -1,482 +0,0 @@
The new 6502 family implementation
----------------------------------
1. Introduction
The new 6502 family implementation has been created to reach
sub-instruction accuracy in observable behaviour. It is designed with
3 goals in mind:
- every bus cycle must happen at the exact time it would happen in a
real cpu, and every access the real cpu does is done
- instructions can be interrupted at any time in the middle then
restarted at that point transparently
- instructions can be interrupted even from within a memory handler
for bus contention/wait states emulation purposes
Point 1 has been ensured through bisimulation with the gate-level
simulation perfect6502. Point 2 has been ensured structurally through
a code generator which will be explained in section 8. Point 3 is not
done yet due to lack of support on the memory subsystem side, but
section 9 shows how it will be handled.
2. The 6502 family
The MOS 6502 family has been large and productive. A large number of
variants exist, varying on bus sizes, i/o, and even opcodes. Some
offshots (g65c816, hu6280) even exist that live elsewhere in the mame
tree. The final class hierarchy is this:
6502
|
+------+--------+--+--+-------+-------+
| | | | | |
6510 deco16 6504 6509 n2a03 65c02
| |
+-----+-----+ r65c02
| | | |
6510t 7501 8502 +---+---+
| |
65ce02 65sc02
|
4510
The 6510 adds an up to 8 bits i/o port, with the 6510t, 7501 and 8502
being software-identical variants with different pin count (hence i/o
count), die process (nmos, hnmos, etc) and clock support.
The deco16 is a Deco variant with a small number of not really understood
additional instructions and some i/o.
The 6504 is a pin and address-bus reduced version.
The 6509 adds internal support for paging.
The n2a03 is the nes variant with the D flag disabled and sound
functionality integrated.
The 65c02 is the very first cmos variant with some additional
instructions, some fixes, and most of the undocumented instructions
turned into nops. The R (rockwell, but eventually produced by wdc too
among others) variant adds a number of bitwise instructions and also
stp and wai. The sc variant, used by the Lynx portable console, looks
identical to the R variant. The 's' probably indicates a
static-ram-cell process allowing full dc-to-max clock control.
The 65ce02 is the final evolution of the ISA in this hierarchy, with
additional instructions, registers, and removals of a lot of dummy
accesses that slowed the original 6502 down by at least 25%. The 4510
is a 65ce02 with integrated mmu and gpio support.
3. Usage of the classes
All the cpus are standard modern cpu devices, with all the normal
interaction with the device infrastructure. To include one of these
cpu in your driver you need to include "cpu/m6502/<cpu>.h" and then do
a MCFG_CPU_ADD("tag", <CPU>, clock).
6510 variants port i/o callbacks are setup through:
MCFG_<CPU>_PORT_CALLBACKS(READ8(type, read_method), WRITE8(type, write_method))
And the pullup and floating lines mask is given through:
MCFG_<CPU>_PORT_PULLS(pullups, floating)
In order to see all bus accesses on the memory handlers it is possible
to disable accesses through the direct map (at a cpu cost, of course)
with:
MCFG_M6502_DISABLE_DIRECT()
In that case, transparent decryption support is also disabled,
everything goes through normal memory-map read/write calls. The state
of the sync line is given by the cpu method get_sync(), making
implementing the decryption in the handler possible.
Also, as for every executable device, the cpu method total_cycles()
gives the current time in cycles since the start of the machine from
the point of view of the cpu. Or, in other words, what is usually
called the cycle number for the cpu when somebody talks about bus
contention or wait states. The call is designed to be fast (no
system-wide sync, no call to machine.time()) and is precise. Cycle
number for every access is exact at the sub-instruction level.
The 4510 special nomap line is accessible through get_nomap().
Other than these specifics, these are perfectly normal cpu classes.
4. General structure of the emulations
Each variant is emulated through up to 4 files:
- <cpu>.h = header for the cpu class
- <cpu>.c = implementation of most of the cpu class
- d<cpu>.lst = dispatch table for the cpu
- o<cpu>.lst = opcode implementation code for the cpu
The last two are optional. They're used to generate a <cpu>.inc file
in the object directory which is included by the .c file.
At a minimum, the class must include a constructor and an enum picking
up the correct input line ids. See m65sc02 for a minimalist example.
The header can also include specific configuration macros (see m8502)
and also the class can include specific memory accessors (more on
these later, simple example in m6504).
If the cpu has its own dispatch table, the class must also include the
declaration (but not definition) of disasm_entries, do_exec_full and
do_exec_partial, the declaration and definition of disasm_disassemble
(identical for all classes but refers to the class-specific
disasm_entries array) and include the .inc file (which provides the
missing definitions). Support for the generation must also be added
to cpu.mak.
If the cpu has in addition its own opcodes, their declaration must be
done through a macro, see f.i. m65c02. The .inc file will provide the
definitions.
5. Dispatch tables
Each d<cpu>.lst is the dispatch table for the cpu. Lines starting
with '#' are comments. The file must include 257 entries, the first
256 being opcodes and the 257th what the cpu should do on reset. In
the 6502 irq and nmi actually magically call the "brk" opcode, hence
the lack of specific description for them.
Entries 0 to 255, i.e. the opcodes, must have one of these two
structures:
- opcode_addressing-mode
- opcode_middle_addressing-mode
Opcode is traditionally a three-character value. Addressing mode must
be a 3-letter value corresponding to one of the DASM_* macros in
m6502.h. Opcode and addressing mode are used to generate the
disassembly table. The full entry text is used in the opcode
description file and the dispatching methods, allowing for per-cpu
variants for identical-looking opcodes.
An entry of "." was usable for unimplemented/unknown opcodes,
generating "???" in the disassembly, but is not a good idea at this
point since it will infloop in execute() if encountered.
6. Opcode descriptions
Each o<cpu>.lst file includes the cpu-specific opcodes descriptions.
An opcode description is a series of lines starting by an opcode entry
by itself and followed by a series of indented lines with code
executing the opcode.
For instance the asl <absolute address> opcode looks like this:
asl_aba
TMP = read_pc();
TMP = set_h(TMP, read_pc());
TMP2 = read(TMP);
write(TMP, TMP2);
TMP2 = do_asl(TMP2);
write(TMP, TMP2);
prefetch();
First the low part of the address is read, then the high part (read_pc
is auto-incrementing). Then, now that the address is available the
value to shift is read, then re-written (yes, the 6502 does that),
shifted then the final result is written (do_asl takes care of the
flags). The instruction finishes with a prefetch of the next
instruction, as all non-cpu-crashing instructions do.
Available bus-accessing functions are:
- read(adr) - standard read
- read_direct(adr) - read from program space
- read_pc() - read at the PC address and increment it
- read_pc_noinc() - read at the PC address
- read_9() - 6509 indexed-y banked read
- write(adr, val) - standard write
- prefetch() - instruction prefetch
- prefetch_noirq() - instruction prefetch without irq check
Cycle counting is done by the code generator which detects (through
string matching) the accesses and generates the appropriate code. In
addition to the bus-accessing functions a special line can be used to
wait for the next event (irq or whatever). "eat-all-cycles;" on a
line will do that wait then continue. It is used by wai_imp and
stp_imp for the m65c02.
Due to the constraints of the code generation, some rules have to be
followed:
- in general, stay with one instruction/expression per line
- there must be no side effects in the parameters of a bus-accessing
function
- local variables lifetime must not go past a bus access. In general,
it's better to leave them to helper methods (like do_asl) which do not
do bus accesses. Note that "TMP" and "TMP2" are not local variables,
they're variables of the class.
- single-line then or else constructs must have braces around them if
they're calling a bus-accessing function
The per-opcode generated code are methods of the cpu class. As such
they have complete access to other methods of the class, variables of
the class, everything.
7. Memory interface
For better opcode reuse with the mmu/banking variants, a memory access
subclass has been created. It's called memory_interface, declared in
m6502_device, and provides the following accessors:
- UINT8 read(UINT16 adr) - normal read
- UINT8 read_sync(UINT16 adr) - opcode read with sync active (first byte of opcode)
- UINT8 read_arg(UINT16 adr) - opcode read with sync inactive (rest of opcode)
- void write(UINT16 adr, UINT8 val) - normal write
- UINT8 read_9(UINT16 adr) - special y-indexed 6509 read, defaults to read()
- void write_9(UINT16 adr, UINT8 val); - special y-indexed 6509 write, defaults to write()
Two implementations are given by default, one usual,
mi_default_normal, one disabling direct access, mi_default_nd. A cpu
that wants its own interface (see 6504 or 6509 for instance) must
override device_start, intialize mintf there then call init().
8. The generated code
A code generator is used to support interrupting and restarting an
instruction in the middle. This is done through a two-level state
machine with updates only at the boundaries. More precisely,
inst_state tells you which main state you're in. It's equal to the
opcode byte when 0-255, and 0xff00 means reset. It's always valid and
used by instructions like rmb. inst_substate indicates at which step
we are in an instruction, but it set only when an instruction has been
interrupted. Let's go back to the asl <abs> code:
asl_aba
TMP = read_pc();
TMP = set_h(TMP, read_pc());
TMP2 = read(TMP);
write(TMP, TMP2);
TMP2 = do_asl(TMP2);
write(TMP, TMP2);
prefetch();
The complete generated code is:
void m6502_device::asl_aba_partial()
{
switch(inst_substate) {
case 0:
if(icount == 0) { inst_substate = 1; return; }
case 1:
TMP = read_pc();
icount--;
if(icount == 0) { inst_substate = 2; return; }
case 2:
TMP = set_h(TMP, read_pc());
icount--;
if(icount == 0) { inst_substate = 3; return; }
case 3:
TMP2 = read(TMP);
icount--;
if(icount == 0) { inst_substate = 4; return; }
case 4:
write(TMP, TMP2);
icount--;
TMP2 = do_asl(TMP2);
if(icount == 0) { inst_substate = 5; return; }
case 5:
write(TMP, TMP2);
icount--;
if(icount == 0) { inst_substate = 6; return; }
case 6:
prefetch();
icount--;
}
inst_substate = 0;
}
One can see that the initial switch() restarts the instruction at the
appropriate substate, that icount is updated after each access, and
upon reaching 0 the instruction is interrupted and the substate
updated. Since most instructions are started from the beginning a
specific variant is generated for when inst_substate is known to be 0:
void m6502_device::asl_aba_full()
{
if(icount == 0) { inst_substate = 1; return; }
TMP = read_pc();
icount--;
if(icount == 0) { inst_substate = 2; return; }
TMP = set_h(TMP, read_pc());
icount--;
if(icount == 0) { inst_substate = 3; return; }
TMP2 = read(TMP);
icount--;
if(icount == 0) { inst_substate = 4; return; }
write(TMP, TMP2);
icount--;
TMP2 = do_asl(TMP2);
if(icount == 0) { inst_substate = 5; return; }
write(TMP, TMP2);
icount--;
if(icount == 0) { inst_substate = 6; return; }
prefetch();
icount--;
}
That variant removes the switch, avoiding a costly computed branch and
also an inst_substate write. There is in addition a fair chance that
the decrement-test with zero pair is compiled into something
efficient.
All these opcode functions are called through two virtual methods,
do_exec_full and do_exec_partial, which are generated into a 257-entry
switch statement. Pointers-to-methods being expensive to call, a
virtual function implementing a switch has a fair chance of being
better.
The execute main call ends up very simple:
void m6502_device::execute_run()
{
if(inst_substate)
do_exec_partial();
while(icount > 0) {
if(inst_state < 0x100) {
PPC = NPC;
inst_state = IR;
if(machine().debug_flags & DEBUG_FLAG_ENABLED)
debugger_instruction_hook(this, NPC);
}
do_exec_full();
}
}
If an instruction was partially executed finish it (icount will then
be zero if it still doesn't finish). Then try to run complete
instructions. The NPC/IR dance is due to the fact that the 6502 does
instruction prefetching, so the instruction PC and opcode come from
the prefetch results.
9. Future bus contention/delay slot support
Supporting bus contention and delay slots in the context of the code
generator only requires being able to abort a bus access when not
enough cycles are available into icount, and restart it when cycles
have become available again. The implementation plan is to:
- Have a delay() method on the cpu that removes cycles from icount.
If icount becomes zero or less, having it throw a suspend() exception.
- Change the code generator to generate this:
void m6502_device::asl_aba_partial()
{
switch(inst_substate) {
case 0:
if(icount == 0) { inst_substate = 1; return; }
case 1:
try {
TMP = read_pc();
} catch(suspend) { inst_substate = 1; return; }
icount--;
if(icount == 0) { inst_substate = 2; return; }
case 2:
try {
TMP = set_h(TMP, read_pc());
} catch(suspend) { inst_substate = 2; return; }
icount--;
if(icount == 0) { inst_substate = 3; return; }
case 3:
try {
TMP2 = read(TMP);
} catch(suspend) { inst_substate = 3; return; }
icount--;
if(icount == 0) { inst_substate = 4; return; }
case 4:
try {
write(TMP, TMP2);
} catch(suspend) { inst_substate = 4; return; }
icount--;
TMP2 = do_asl(TMP2);
if(icount == 0) { inst_substate = 5; return; }
case 5:
try {
write(TMP, TMP2);
} catch(suspend) { inst_substate = 5; return; }
icount--;
if(icount == 0) { inst_substate = 6; return; }
case 6:
try {
prefetch();
} catch(suspend) { inst_substate = 6; return; }
icount--;
}
inst_substate = 0;
}
A modern try/catch costs nothing if an exception is not thrown. Using
this the control will go back to the main loop, which will then look
like this:
void m6502_device::execute_run()
{
if(waiting_cycles) {
icount -= waiting_cycles;
waiting_cycles = 0;
}
if(icount > 0 && inst_substate)
do_exec_partial();
while(icount > 0) {
if(inst_state < 0x100) {
PPC = NPC;
inst_state = IR;
if(machine().debug_flags & DEBUG_FLAG_ENABLED)
debugger_instruction_hook(this, NPC);
}
do_exec_full();
}
waiting_cycles = -icount;
icount = 0;
}
A negative icount means that the cpu won't be able to do anything for
some time in the future, because it's either waiting for the bus to be
free or for a peripheral to answer. These cycles will be counted
until elapsed and then normal processing will go on. It's important
to note that the exception path only happens when the contention/wait
state goes further than the scheduling slice of the cpu. That should
not usually be the case, so the cost should be minimal.
10. Multi-dispatch variants
Some variants currently in the process of being supported change
instruction set depending on an internal flag, either switching to a
16-bits mode or changing some register accesses to memory accesses.
This is handled by having multiple dispatch tables for the cpu, the
d<cpu>.lst not being 257 entries anymore but 256*n+1. The variable
inst_state_base must select which instruction table to use at a given
time. It must be a multiple of 256, and is in fact simply or-ed to
the first instruction byte to get the dispatch table index (aka
inst_state).
11. Current TODO
- Implement the bus contention/wait states stuff, but that requires
support on the memory map side first.
- Integrate the i/o subsystems in the 4510
- Possibly integrate the sound subsytem in the n2a03
- Add decent hookups for the apple 3 madness

65
docs/mame.txt
View File

@ -1,65 +0,0 @@
MAME(r)
Copyright (c) 1997-2016 by MAMEdev and contributors
MAME is a registered trademark of Nicola Salmoria
----------
I. Purpose
----------
MAME main purpose is to be a reference to the inner workings of the
emulated machines. This is done both for educational purposes and for
preservation purposes, in order to prevent historical software from
disappearing forever once the hardware it runs on stops working. Of
course, in order to preserve the software and demonstrate that the
emulated behavior matches the original, one must also be able to
actually use the software. This is considered a nice side effect, and is
not MAME's primary focus.
It is not our intention to infringe on any copyrights or patents on the
original games. All of MAME's source code is either our own or freely
available. To operate, the emulator requires images of the original
ROMs, CDs, hard disks or other media from the machines, which must be
provided by the user. No portions of the original game code are included
in the executable.
--------
II. Cost
--------
MAME is free. Its source code is free. The project as whole is
distributed under the GNU General Public License, version 2 or later
(GPL-2.0+), but most of code (including core functionality) is also
available under the 3-clause BSD license (BSD-3-clause).
-------------------------
III. Software Image Files
-------------------------
ROM, CD, hard disk and other media images are all copyrighted material.
They cannot be distributed without the explicit permission of the
copyright holder(s). They are not "abandonware", nor has any of the
software supported by MAME passed out of copyright.
MAME is not intended to be used as a tool for mass copyright
infringement. Therefore, it is strongly against the authors' wishes to
sell, advertise, or link to resources that provide illegal copies of
ROM, CD, hard disk or other media images.
--------------------
IV. Derivative Works
--------------------
Because the name MAME is trademarked, you must abide by the rules set
out for trademark usage if you wish to use "MAME" as part of the name
your derivative work. In general, this means you must request
permission, which requires that you follow the guidelines above.
The version number of any derivative work should reflect the version
number of the MAME release from which it was was derived.
-------------------------------
V. Official Contact Information
-------------------------------
For questions regarding the MAME license, trademark, or other usage, go
to http://www.mamedev.org/

146
docs/newvideo.txt
View File

@ -1,146 +0,0 @@
This article originally appeared in a slightly different form at
http://aarongiles.com. You should read this if you are used to how
MAME's video system worked prior to 0.107 and you want to understand
how you should configure MAME with the new rendering system in place.
The New Video Landscape
Since its inception 9 years ago, MAME's video system has defaulted to
a mode where it tries to change resolutions on you. And since the
first port of the core to Windows 5 years ago, it has defaulted to
using your graphics card to stretch the video to that resolution.
I'm sure a lot of you out there have taken a lot of time to tweak the
current set of video options to make them work the way you like. But
every once in a while, you need to take a step back and re-evaluate
the situation. The current video system has been in place for 5 years
now without much substantial change. And with the recent rewrite,
you're almost certainly going to want to rethink the way you have
things configured.
At the highest level, there are really three different ways you can
configure the new system. Placing yourself into one of these three
categories will help you get the initial settings right. From there,
you can tweak with the settings to figure out what works best.
Category 1: Bells and whistles. People who fall into this category
would include anyone with a modern system and a decent video card
(decent in this context means at least 16MB of VRAM and built in the
last 5 years or so -- we're not talking cutting edge here). Any decent
video card will be able to render the simple MAME graphics at pretty
much any resolution without breaking a sweat. Configure your desktop
to the video mode you want (preferably something high like 1024x768
or greater with a high refresh rate, unless you are running on a
fixed-mode LCD, in which case just match what your LCD panel is),
and tell MAME to leave the resolution alone. In this day and age,
there is little reason to switch resolutions at all, unless you
fall into Category 3, below. In this mode, you will have full access
to artwork options, and you'll get your artwork scaled to full
resolution and with full alpha blending effects. Vector games will
look crisp, you can use decent fonts, and you can see a whole lot
more of the world when using the graphics/tilemap viewer. This mode
uses Direct3D, so you should configure yourself like this:
-video d3d -noswitchres [-triplebuffer] [-nofilter]
The -noswitchres option tells MAME to just run at the current
resolution. Although you can let MAME pick a resolution for you, it
doesn't really make much sense in D3D mode, and in fact I may even
remove that feature altogether. To avoid tearing artifacts, I
recommend using the -triplebuffer option as well. Just make sure your
monitor's refresh rate is higher than the game you are running. If
you dislike the blurry look of the graphics, you can specify the
-nofilter option to disable bilinear filtering, though that will
produce blocky artifacts. Alternatively, you can use the -prescale
option which is described at the end of this article.
Category 2: Like the old days. I really didn't even want to support
this mode at all, but certain vocal MAMEdevs would have skinned me
alive otherwise. People who fall into this category include those who
have weak systems that worked fine with previous versions of MAME,
but who don't run well with Direct3D rendering. (Note that just
because Space Invaders runs unthrottled at 2000fps with DirectDraw
and 1000fps with Direct3D doesn't mean that Direct3D is going to be
a serious issue when playing at a regular 60fps, so if you're unsure,
give the Direct3D route a try for a while.) In this mode, MAME will
draw the game screen and artwork at the game's resolution, just like
it did in MAME 0.106 and earlier; however, some artwork options,
such as -artcrop, won't work as you might expect, and some alpha
blending artwork modes (specifically overlays) will operate with a
performance penality. MAME will then use your video card to stretch
the video to the proper aspect ratio.
-video ddraw -hwstretch [-switchres] [-triplebuffer]
The -switchres is optional here. If your video card is really ancient
and struggles expanding the screen to fit your desktop resolution,
you might want to turn it on. Again, to avoid tearing artifacts, I
recommend using the -triplebuffer option as well, but make sure your
monitor's refresh rate is higher than the game you are running
(-switchres will do that for you if you use it). If your video card
produces blurry pixels which you don't like, try the -prescale option
described at the end of this article.
Category 3: Anal video mode types. These are the guys who have
generally built their own cabinets and set them up with a CRT display
where they have several dozen carefully hand-tweaked video modes that
approximate the original video modes the games ran at. They want MAME
to pick that hand-tweaked mode and use it, drawing one pixel on the
screen for each pixel in the original game. They don't give a whit
about artwork or anything other than the raw pixels going to the
right place. Fortunately, you can still configure MAME for this case
as well:
-video ddraw -nohwstretch -switchres [-triplebuffer]
Obviously in this case, the -switchres is required. You also want to
disable hardware stretching, otherwise you won't get that "perfect"
1:1 pixel mapping. Triple buffering may or may not help.
So, I recommend starting with these initial options and then tweaking
from there. One additional option you might want to try in
combination with the above is the -prescale option. -prescale takes
an integer parameter from 1 to 3, and specifies a magnification
amount by which the screen pixels are expanded before they are drawn
to the screen. Why is this useful? And how much of a performance
impact does it have? Well, that depends on the mode you are running
in.
If you are running in Category 1 (-video d3d), then -prescale will
use your video card to scale the game graphics up before rendering
them to the screen. Depending on the video card, this is usually a
small performance hit, but not too significant. The benefit is that
each prescale factor reduces the blurriness of the pixels.
-prescale 1 is the default, which does no scaling. -prescale 2 will
double each pixel, and -prescale 3 will triple each pixel. For my
money, -prescale 2 is sufficient, but people with super high
resolution displays claim that larger -prescale factors work even
better.
If you are running in Category 2 (-video ddraw -hwstretch), then
-prescale will cause MAME to compose the screen graphics at the
specified scale factor. This is unfortunately done in software, but
carries the benefit that artwork, fonts, and the graphics viewer can
take advantage of the additional resolution to produce nicer results.
The end effect is that you will get less blurry pixels, just like the
Category 1 case, plus higher quality artwork, fonts, and more visible
area in the graphics viewer.
If you are running in Category 3 (-video ddraw -nohwstretch), then
-prescale will cause MAME to pick a video mode that is the prescale
factor times the raw screen resolution, and then MAME will, in
software, compose the screen graphics at the specified scale factor.
This has all the advantages of the Category 2 case, except that since
there wasn't any pixel blurring to begin with, there is no additional
crispness that comes about as a result.
Finally, you may be wondering about effects (and yes, scanlines are
an "effect"). Effects are no longer hard-coded into the system.
Rather, you can provide a PNG file in the artwork directory that will
be loaded and overlaid on top of screen bitmaps. See the description
of -effect in windows.txt for more details.

234
docs/nscsi.txt
View File

@ -1,234 +0,0 @@
The new SCSI subsystem
----------------------
1. Introduction
The nscsi subsystem was created to allow an implementation to be
closer to the physical reality, making it easier (hopefully) to
implement new controller chips from the documentations.
2. Global structure
Parallel SCSI is built around a symmetric bus to which a number of
devices are connected. The bus is composed of 9 control lines (for
now, later scsi versions may have more) and up to 32 data lines (but
currently implemented chips only handle 8). All the lines are open
collector, which means that either one or multiple chip connect the
line to ground and the line, of course, goes to ground, or no chip
drives anything and the line stays at Vcc. Also, the bus uses
inverted logic, where ground means 1. SCSI chips traditionally work
in logical and not physical levels, so the nscsi subsystem also works
in logical levels and does a logical-or of all the outputs of the
devices.
Structurally, the implementation is done around two main classes:
nscsi_bus_devices represents the bus, and nscsi_device represents an
individual device. A device only communicate with the bus, and the
bus takes care of transparently handling the device discovery and
communication. In addition the nscsi_full_device class proposes a
scsi device with the scsi protocol implemented making building generic
scsi devices like harddrives or cdrom readers easier.
3. Plugging in a scsi bus in a driver
The nscsi subsystem leverages the slot interfaces and the device
naming to allow for a configurable yet simple bus implementation.
First you need to create a list of acceptable devices to plug on the
bus. This usually comprises of cdrom, harddisk and the controller
chip. For instance:
static SLOT_INTERFACE_START( next_scsi_devices )
SLOT_INTERFACE("cdrom", NSCSI_CDROM)
SLOT_INTERFACE("harddisk", NSCSI_HARDDISK)
SLOT_INTERFACE_INTERNAL("ncr5390", NCR5390)
SLOT_INTERFACE_END
The _INTERNAL interface indicates a device that is not
user-selectable, which is useful for the controller.
Then in the machine config (or in a fragment config) you need to first
add the bus, and then the (potential) devices as subdevices of the bus
with the scsi id as the name. For instance you can use:
MCFG_NSCSI_BUS_ADD("scsibus")
MCFG_NSCSI_ADD("scsibus:0", next_scsi_devices, "cdrom", 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:1", next_scsi_devices, "harddisk", 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:2", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:3", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:4", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:5", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:6", next_scsi_devices, 0, 0, 0, 0, false)
MCFG_NSCSI_ADD("scsibus:7", next_scsi_devices, "ncr5390", 0, &next_ncr5390_interface, 10000000, true)
That configuration puts as default a cdrom reader on scsi id 0 and a
hard drive on scsi id 1, and forces the controller on id 7. The
parameters of add are:
- device tag, comprised of bus-tag:scsi-id
- the list of acceptable devices
- the device name as per the list, if one is to be there by default
- the device input config, if any (and there usually isn't one)
- the device configuration structure, usually for the controller only
- the frequency, usually for the controller only
- "false" for a user-modifyable slot, "true" for a fixed slot
The full device name, for mapping purposes, will be
bus-tag:scsi-id:device-type, i.e. "scsibus:7:ncr5390" for our
controller here.
4. Creating a new scsi device using nscsi_device
The base class "nscsi_device" is to be used for down-to-the-metal
devices, i.e. scsi controller chips. The class provides three
variables and one method. The first variable, scsi_bus, is a pointer
to the nscsi_bus_device. The second, scsi_refid, is an opaque
reference to pass to the bus on some operations. Finally, scsi_id
gives the scsi id as per the device tag. It's written once at startup
and never written or read afterwards, the device can do whatever it
wants with the value or the variable.
The virtual method scsi_ctrl_changed is called when watched-for
control lines change. Which lines are watched is defined through the
bus.
The bus proposes five methods to access the lines. The read methods
are ctrl_r() and data_r(). The meaning of the control bits are
defined in the S_* enum of nscsi_device. The bottom three bits (INP,
CTL and MSG) are setup so that masking with 7 (S_PHASE_MASK) gives the
traditional numbers for the phases, which are also available with the
S_PHASE_* enum.
Writing the data lines is done with data_w(scsi_refid, value).
Writing the control lines is done with ctrl_w(scsi_refid, value,
mask-of-lines-to-change). To change all control lines in one call use
S_ALL as the mask.
Of course, what is read is the logical-or of all of what is driven by
all devices.
Finally, the method ctrl_wait_w(scsi_id, value,
mask-of-wait-lines-to-change) allows to select which control lines are
watched. The watch mask is per-device, and the device method
scsi_ctrl_changed is called whenever a control line in the mask
changes due to an action of another device (not itself, to avoid an
annoying and somewhat useless recursion).
Implementing the controller is then just a matter of following the
state machines descriptions, at least if they're available. The only
part often not described is the arbitration/selection, which is
documented in the scsi standard though. For an initiator (which is
what the controller essentially always is), it goes like this:
- wait for the bus to be idle
- assert the data line which number is your scsi_id (1 << scsi_id)
- assert the busy line
- wait the arbitration time
- check that the of the active data lines the one with the highest number is yours
- if no, the arbitration was lost, stop driving anything and restart at the beginning
- assert the select line (at that point, the bus is yours)
- wait a short while
- keep your data line asserted, assert the data line which number is the scsi id of the target
- wait a short while
- assert the atn line if needed, deassert busy
- wait for busy to be asserted or timeout
- timeout means nobody is answering at that id, deassert everything and stop
- wait a short while for deskewing
- deassert the data bus and the select line
- wait a short while
and then you're done, you're connected with the target until the
target deasserts the busy line, either because you asked it to or just
to annoy you. The deassert is called a disconnect.
The ncr5390 is an example of how to use a two-level state machine to
handle all the events.
5. Creating a new scsi device using nscsi_full_device
The base class "nscsi_full_device" is used to create HLE-d scsi
devices intended for generic uses, like hard drives, cdroms, perhaps
scanners, etc. The class provides the scsi protocol handling, leaving
only the command handling and (optionally) the message handling to the
implementation.
The class currently only support target devices.
The first method to implement is scsi_command(). That method is
called when a command has fully arrived. The command is available in
scsi_cmdbuf[], and its length is in scsi_cmdsize (but the length is
generally useless, the command first byte giving it). The 4096-bytes
scsi_cmdbuf array is then freely modifiable.
In scsi_command(), the device can either handle the command or pass it
up with nscsi_full_device::scsi_command().
To handle the command, a number of methods are available:
- get_lun(lua-set-in-command) will give you the lun to work on (the
in-command one can be overriden by a message-level one).
- bad_lun() replies to the host that the specific lun is unsupported.
- scsi_data_in(buffer-id, size) sends size bytes from buffer buffer-id
- scsi_data_out(buffer-id, size) recieves size bytes into buffer buffer-id
- scsi_status_complete(status) ends the command with a given status.
- sense(deferred, key) prepares the sense buffer for a subsequent
request-sense command, which is useful when returning a
check-condition status.
The scsi_data_* and scsi_status_complete commands are queued, the
command handler should call them all without waiting.
buffer-id identifies a buffer. 0, aka SBUF_MAIN, targets the
scsi_cmdbuf buffer. Other acceptable values are 2 or more. 2+ ids
are handled through the scsi_get_data method for read and
scsi_put_data for write.
UINT8 device::scsi_get_data(int id, int pos) must return byte pos of
buffer id, upcalling in nscsi_full_device for id < 2.
void device::scsi_put_data(int id, int pos, UINT8 data) must write
byte pos in buffer id, upcalling in nscsi_full_device for id < 2.
scsi_get_data and scsi_put_data should do the external reads/writes
when needed.
The device can also override scsi_message to handle scsi messages
other than the ones generically handled, and it can also override some
of the timings (but a lot of them aren't used, beware).
A number of enums are defined to make things easier. The SS_* enum
gives status returns (with SS_GOOD for all's well). The SC_* enum
gives the scsi commands. The SM_* enum gives the scsi messages, with
the exception of identify (which is 80-ff, doesn't really fit in an
enum).
6. What's missing
6.1. What's missing in scsi_full_device
Initiator support - we have no initiator device to HLE at that point.
Delays - a scsi_delay command would help giving more realistic timings
to the cdrom reader in particular.
Disconnected operation - would first require delays and in addition an
emulated OS that can handle it.
16-bits wide operation - needs an OS and an initiator that can handle
it.
6.2. What's missing in the ncr5390 (and probably future other controllers)
Bus free detection. Right now the bus is considered free if the
controllers isn't using it, which is true. This may change once
disconnected operation is in.
Target commands, we don't emulate (vs. HLE) any target yet.

370
docs/windows.txt
View File

@ -1,370 +0,0 @@
This file describes Windows-specific usage information about MAME. It is
intended to cover aspects of using and configuring the program that are
specific to running MAME from the command line on a Windows-based system.
For common options that apply to all systems, please see config.txt.
In addition to the keys described in config.txt, the following additional
keys are defined for Windows versions of MAME:
Windows debugging options
-------------------------
-[no]oslog
Outputs the error.log data to the Windows debugger. This can be used at
the same time as -log to output the log data to both targets as well.
Default is OFF (-nooslog).
-watchdog <duration> / -wdog <duration>
Enables an internal watchdog timer that will automatically kill the MAME
process if more than <duration> seconds passes without a frame update.
Keep in mind that some games sit for a while during load time without
updating the screen, so <duration> should be long enough to cover that.
10-30 seconds on a modern system should be plenty in general. By default
there is no watchdog.
-debugger_font <fontname> / -dfont <fontname>
Specifies the name of the font to use for debugger windows. By default,
the font is Lucida Console.
-debugger_font_size <points> / -dfontsize <points>
Specifies the size of the font to use for debugger windows, in points.
By default, this is set to 9pt.
Windows performance options
---------------------------
-priority <priority>
Sets the thread priority for the MAME threads. By default the priority
is left alone to guarantee proper cooperation with other applications.
The valid range is -15 to 1, with 1 being the highest priority. The
default is 0 (NORMAL priority).
-[no]multithreading / -[no]mt
Enables multithreading within MAME. At the moment, this causes the
window and all DirectDraw/Direct3D code to execute on a second thread,
which can improve performance on hyperthreaded and multicore systems.
The default is OFF (-nomultithreading).
-numprocessors <auto|value> / -np <auto|value>
Specify the number of processors to use for work queues. Specifying
"auto" will use the value reported by the system or environment
variable OSDPROCESSORS. To avoid abuse, this value is internally limited
to 4 times the number of processors reported by the system.
The default is "auto".
-profile [n]
Enables profiling, specifying the stack depth of [n] to track.
-bench [n]
Benchmark for [n] number of emulated seconds; implies the command string:
-str [n] -video none -sound none -nothrottle
Windows video options
---------------------
-video <gdi|ddraw|d3d|none>
Specifies which video subsystem to use for drawing. By specifying 'gdi'
here, you tell MAME to render video using standard Windows graphics
drawing calls. This is the slowest but most compatible option.
Specifying 'ddraw' instructs MAME to use DirectDraw for rendering.
This causes MAME to render everything at a lower resolution and then
upscale the results at the end. This produces high performance,
especially on older or low-power video cards, but has a noticeably
lower output quality. Specifying 'd3d' tells MAME to use Direct3D for
rendering. This produces the highest quality output and enables all
rendering options. It is recommended if you have a recent (2002+)
video card. The final option 'none' displays no windows and does no
drawing. This is primarily present for doing CPU benchmarks without
the overhead of the video system. The default is d3d.
-numscreens <count>
Tells MAME how many output windows to create. For most games, a single
output window is all you need, but some games originally used multiple
screens. Each screen (up to 4) has its own independent settings for
physical monitor, aspect ratio, resolution, and view, which can be
set using the options below. The default is 1.
-[no]window / -[no]w
Run MAME in either a window or full screen. The default is OFF
(-nowindow).
-[no]maximize / -[no]max
Controls initial window size in windowed mode. If it is set on, the
window will initially be set to the maximum supported size when you
start MAME. If it is turned off, the window will start out at the
smallest supported size. This option only has an effect when the
-window option is used. The default is ON (-maximize).
-[no]keepaspect / -[no]ka
Enables aspect ratio enforcement. When this option is on, the game's
proper aspect ratio (generally 4:3 or 3:4) is enforced, so you get the
game looking like it should. When running in a window with this option
on, you can only resize the window to the proper aspect ratio, unless
you are holding down the CONTROL key. By turning the option off, the
aspect ratio is allowed to float. In full screen mode, this means that
all games will stretch to the full screen size (even vertical games).
In window mode, it means that you can freely resize the window without
any constraints. The default is ON (-keepaspect).
-prescale <amount>
Controls the size of the screen images when they are passed off to the
graphics system for scaling. At the minimum setting of 1, the screen
is rendered at its original resolution before being scaled. At higher
settings, the screen is expanded by a factor of <amount> before being
scaled. With -video ddraw or -video d3d, this produces a less blurry
image at the expense of some speed. In -video ddraw mode, this also
increases the effective resolution of non-screen elements such as
artwork and fonts. The default is 1.
-[no]waitvsync
Waits for the refresh period on your computer's monitor to finish
before starting to draw video to your screen. If this option is off,
MAME will just draw to the screen at any old time, even in the middle
of a refresh cycle. This can cause "tearing" artifacts, where the top
portion of the screen is out of sync with the bottom portion. Tearing
is not noticeable on all games, and some people hate it more than
others. However, if you turn this option on, you will waste more of
your CPU cycles waiting for the proper time to draw, so you will see a
performance hit. You should only need to turn this on in windowed mode.
In full screen mode, it is only needed if -triplebuffer does not
remove the tearing, in which case you should use -notriplebuffer
-waitvsync. Note that this option does not work with -video gdi mode.
The default is OFF (-nowaitvsync).
-[no]syncrefresh
Enables speed throttling only to the refresh of your monitor. This
means that the game's actual refresh rate is ignored; however, the
sound code still attempts to keep up with the game's original refresh
rate, so you may encounter sound problems. This option is intended
mainly for those who have tweaked their video card's settings to
provide carefully matched refresh rate options. Note that this option
does not work with -video gdi mode.The default is OFF (-nosyncrefresh).
DirectDraw-specific options
---------------------------
-[no]hwstretch / -[no]hws
When enabled, MAME uses the hardware stretching abilities of your
video card to scale the game image and associated artwork to the
target resolution. Depending on the quality of your graphic card and
its drivers, this may be a fractional, antialiased scaling (nice) or
an integer, blocky scaling (not so nice), in which case you might want
to disable this option. In addition, if you have configured specific
arcade-like video modes for MAME and don't want MAME to perform any
non-integral scaling of the image, you should also disable this option.
The default is ON (-hwstretch).
Direct3D-specific options
-------------------------
-[no]filter / -[no]d3dfilter / -[no]flt
Enable bilinear filtering on the game screen graphics. When disabled,
point filtering is applied, which is crisper but leads to scaling
artifacts. If you don't like the filtered look, you are probably better
off increasing the -prescale value rather than turning off filtering
altogether. The default is ON (-filter).
Per-window options
------------------
-screen <display>
-screen0 <display>
-screen1 <display>
-screen2 <display>
-screen3 <display>
Specifies which physical monitor on your system you wish to have each
window use by default. In order to use multiple windows, you must have
increased the value of the -numscreens option. The name of each
display in your system can be determined by running MAME with the
-verbose option. The display names are typically in the format of:
\\.\DISPLAYn, where 'n' is a number from 1 to the number of connected
monitors. The default value for these options is 'auto', which means
that the first window is placed on the first display, the second
window on the second display, etc.
The -screen0, -screen1, -screen2, -screen3 parameters apply to the
specific window. The -screen parameter applies to all windows. The
window-specific options override values from the all window option.
-aspect <width:height> / -screen_aspect <num:den>
-aspect0 <width:height>
-aspect1 <width:height>
-aspect2 <width:height>
-aspect3 <width:height>
Specifies the physical aspect ratio of the physical monitor for each
window. In order to use multiple windows, you must have increased the
value of the -numscreens option. The physical aspect ratio can be
determined by measuring the width and height of the visible screen
image and specifying them separated by a colon. The default value for
these options is 'auto', which means that MAME assumes the aspect
ratio is proportional to the number of pixels in the desktop video
mode for each monitor.
The -aspect0, -aspect1, -aspect2, -aspect3 parameters apply to the
specific window. The -aspect parameter applies to all windows. The
window-specific options override values from the all window option.
-resolution <widthxheight[@refresh]> / -r <widthxheight[@refresh]>
-resolution0 <widthxheight[@refresh]> / -r0 <widthxheight[@refresh]>
-resolution1 <widthxheight[@refresh]> / -r1 <widthxheight[@refresh]>
-resolution2 <widthxheight[@refresh]> / -r2 <widthxheight[@refresh]>
-resolution3 <widthxheight[@refresh]> / -r3 <widthxheight[@refresh]>
Specifies an exact resolution to run in. In full screen mode, MAME
will try to use the specific resolution you request. The width and
height are required; the refresh rate is optional. If omitted or
set to 0, MAME will determine the mode auomatically. For example,
-resolution 640x480 will force 640x480 resolution, but MAME is free to
choose the refresh rate. Similarly, -resolution 0x0@60 will force a
60Hz refresh rate, but allows MAME to choose the resolution. The
string "auto" is also supported, and is equivalent to 0x0@0. In window
mode, this resolution is used as a maximum size for the window. This
option requires the -switchres option as well in order to actually
enable resolution switching with -video ddraw or -video d3d. The
default value for these options is 'auto'.
The -resolution0, -resolution1, -resolution2, -resolution3 parameters
apply to the specific window. The -resolution parameter applies to all
windows. The window-specific options override values from the all
window option.
-view <viewname>
-view0 <viewname>
-view1 <viewname>
-view2 <viewname>
-view3 <viewname>
Specifies the initial view setting for each window. The <viewname>
does not need to be a perfect match; rather, it will select the first
view whose name matches all the characters specified by <viewname>.
For example, -view native will match the "Native (15:14)" view even
though it is not a perfect match. The value 'auto' is also supported,
and requests that MAME perform a default selection. The default value
for these options is 'auto'.
The -view0, -view1, -view2, -view3 parameters apply to the
specific window. The -view parameter applies to all windows. The
window-specific options override values from the all window option.
Full screen options
-------------------
-[no]triplebuffer / -[no]tb
Enables or disables "triple buffering". Normally, MAME just draws
directly to the screen, without any fancy buffering. But with this
option enabled, MAME creates three buffers to draw to, and cycles
between them in order. It attempts to keep things flowing such that one
buffer is currently displayed, the second buffer is waiting to be
displayed, and the third buffer is being drawn to. -triplebuffer will
override -waitvsync, if the buffer is sucessfully created. This option
does not work with -video gdi. The default is OFF (-notriplebuffer).
-[no]switchres
Enables resolution switching. This option is required for the
-resolution* options to switch resolutions in full screen mode. On
modern video cards, there is little reason to switch resolutions unless
you are trying to achieve the "exact" pixel resolutions of the original
games, which requires significant tweaking. This option is also useful
on LCD displays, since they run with a fixed resolution and switching
resolutions on them is just silly. This option does not work with
-video gdi. The default is OFF (-noswitchres).
-full_screen_brightness / -fsb <value>
Controls the brightness, or black level, of the entire display. The
standard value is 1.0. Selecting lower values (down to 0.1) will produce
a darkened display, while selecting higher values (up to 2.0) will
give a brighter display. Note that not all video cards have hardware to
support this option. This option does not work with -video gdi. The
default is 1.0.
-full_screen_contrast / -fsc <value>
Controls the contrast, or white level, of the entire display. The
standard value is 1.0. Selecting lower values (down to 0.1) will produce
a dimmer display, while selecting higher values (up to 2.0) will
give a more saturated display. Note that not all video cards have
hardware to support this option. This option does not work with
-video gdi. The default is 1.0.
-full_screen_gamma / -fsg <value>
Controls the gamma, which produces a potentially nonlinear black to
white ramp, for the entire display. The standard value is 1.0, which
gives a linear ramp from black to white. Selecting lower values (down
to 0.1) will increase the nonlinearity toward black, while selecting
higher values (up to 3.0) will push the nonlinearity toward white. Note
that not all video cards have hardware to support this option. This
option does not work with -video gdi. The default is 1.0.
Windows sound options
---------------------
-sound <dsound|sdl|none>
Specifies which sound subsystem to use. 'none' disables sound altogether.
The default is dsound.
-audio_latency <value>
This controls the amount of latency built into the audio streaming. By
default MAME tries to keep the DirectSound audio buffer between 1/5 and
2/5 full. On some systems, this is pushing it too close to the edge,
and you get poor sound sometimes. The latency parameter controls the
lower threshold. The default is 1 (meaning lower=1/5 and upper=2/5).
Set it to 2 (-audio_latency 2) to keep the sound buffer between 2/5 and
3/5 full. If you crank it up to 4, you can definitely notice the lag.
Input device options
--------------------
-[no]dual_lightgun / -[no]dual
Controls whether or not MAME attempts to track two lightguns connected
at the same time. This option requires -lightgun. This option is a hack
for supporting older dual lightgun setups. If you have multiple
lightguns connected, you will probably just need to enable -mouse and
configure each lightgun independently. The default is OFF
(-nodual_lightgun).