
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 +                      SilkMouse version 4.1                      +
 +                   for Atari ST/STe/TT/Falcon                    +
 +           FREEWARE, Copyright (c) 1996 by Mark Slagell          +
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

October 6, 1996


 Purpose
 =======

SilkMouse is the definitive mouse accelerator for Atari TOS
computers.  It may be used by itself or in conjunction with Codehead
Software's popular Warp 9 package, replacing its mouse accelerator. 
It is also fully compatible with serial mouse drivers.
  
The acceleration algorithm has been entirely reconceived since the
release three years ago of version 3.2.  More sophisticated
mathematics have been employed to help you control the mouse pointer
with less effort.

A few options are included that you may find handy, but can be
disabled where they are not needed.  These include a simple screen
saver, a hold-screen switch for terminating applications, and a patch
preventing a specific glitch that some Atari keyboards are prone to. 
The options are detailed later in this document.

The resident part of SilkMouse is written entirely in assembly
language for speed and compactness.


 Installation
 ============

Delete or otherwise disable any mouse accelerator currently installed
on your system, including any previous version of SilkMouse.  If you
are using a serial mouse or some other driver with acceleration that
can't be entirely disabled, adjust it down (for MOUSE.PRG, set
"speedup" to around 15).

Run SILKMOUS.PRG from the desktop, or copy it to your AUTO folder and
reboot.

When first installed, SilkMouse 4.1 is inactive until you set
preferences using SMCP.ACC, the SilkMouse Control Panel.  It can be
installed as an accessory or renamed (as, for example, SMCP.APP) and
run from the desktop.

After you have saved preferences, SILKMOUS.PRG finds that information
by itself the next time it installs.  You do not need to leave SMCP
installed to use SilkMouse.

A CPX version of SMCP is not currently planned for this version.


 Some characteristics of the SilkMouse accelerator
 =================================================

1: extremely smooth response, without gears or plateaus
2: smaller physical motions needed to reach any point on screen
3: easy single-pixel control
4: fine adjustability of response curve
5: resolution independence, no adjusting for different aspect ratios
6: angle of motion faithfully reproduced
7: predictable operation of Alt-arrow keys.

SilkMouse is uniquely able to overcome the resolution limitations of
both the screen and the mouse device.  Regardless of screen mode,
coordinates are maintained internally on a virtual 1-micron grid, and
adjustments are continuously made from accumulated rounding errors.

Physical mouse speed is determined not from the raw X and Y
components reported by the IKBD processor, but from the magnitude of
the resulting vector (the Pythagorean theorem is used, with
fixed-point binary values taken from a table to avoid having to
compute square roots on the fly), and the elapsed time between mouse
motion reports.  This extra information allows discrimination between
much lower physical speeds than is possible with a conventional
accelerator, effectively increasing the resolution of the mouse and
allowing you to expend less energy to get the results you want.


 Accelerator configuration
 =========================

To adjust mouse response, click on "Mouse accelerator: Config" in the
SMCP accessory.  You will see five slider-based adjustments and two
switches.

To understand the first four adjustments, think of a response curve
plotted with physical mouse speed along the X axis and acceleration
factor along the Y axis.  SMCP draws the curve to fit three points. 
Think of these as (x0,y0), (x1,y1), and (x2,y2).

Of those sliders adjusting acceleration, Min, Avg and Max correspond
respectively to y0, y1 and y2.  These should be adjusted according to
work habits and personal taste.

Coordinate x0 is fixed at theoretical speed zero, and x2 at a speed
Nolan Ryan, hurling the mouse across a desktop, could not have
achieved in his prime.  The sensitivity adjustment corresponds to x1,
though its slider is calibrated inversely to the graph axis so the
description makes better intuitive sense.  I suggest setting this to
reflect physical considerations; for instance, you might reduce it if
using a high-resolution mouse, or increase it if you have small hands.

The sliders described above have been calibrated for a range of 0 to
100.  I suggest starting them around the middle and working outward
until you find your best response curve.

The fifth adjustment, "Drag weight", causes acceleration to
automatically decrease when a mouse button is being pressed.  This
both enhances control of free-hand drawing and gives a sense of weight
when something is being dragged, as the description suggests.  From a
range of 0 to 12, the default setting is 1.  When set to zero, the
mouse button state has no affect on acceleration.

Contour type I maintains strict resolution independence at all
speeds; in some circumstances that means actually decelerating, not
accelerating, the pointer response.  For those who find that behavior
disconcerting, contour type II blends in raw pulse data at the low end
of the response curve, preventing deceleration and making the "Min
accel" adjustment less critical.  Choose the contour type that seems
to give you better single-pixel control.

Leave "VDI pixel dimensions" on unless you experience odd behavior. 
Atari maintains documented but seldom-used system variables for the
height and width of a pixel.  If you have installed something that
changes screen modes without updating those variables (SEBRA is guilty
of this oversight), turn this switch off and SilkMouse will calculate
pixel dimensions based on other information.

(My personal settings when using a standard Atari mouse are:
  Min accel: 72
  Avg accel: 62
  Max accel: 50
  Sensitivity: 50
  Drag weight: 2
  Contour type I
  VDI pixel dimensions ON.)


 The screen saver
 ================

Included with SilkMouse is an optional screen saver whose purpose is
not to entertain or amuse, but to extend the useful life of your
monitor without getting in the way of your work.

When a color monitor is in use, the saver works as follows: after a
given period where no input from the mouse or keyboard is received,
the display inverts and goes to half intensity (black becomes gray,
white becomes black, bright yellow becomes dark blue, etc.).  It
remains in this state for a time that is some multiple of the initial
delay, then goes blank.  Moving the mouse or pressing a key at any
time returns the display to normal.  (As of version 4.1, the screen
saver correctly recognizes activity of a serial mouse.)

The invert/dim algorithm is good for your monitor, because it assures
even use of all areas of the screen to prevent phosphor burn-in; it
is also convenient, since the information in the display remains
viewable for a while even after protection begins.

When a monochrome monitor is in use, a screenful of memory may
optionally be reserved during bootup.  (Note: turning the "mono
reserve" switch on or off has no effect until after you save
preferences and reboot.)  Having the extra memory available allows the
saver to mimic its color behavior when the hardware does not support
palette manipulation.  When changing states from normal to dimmed, the
screen is inverted if the background was white, or every other pixel
is turned off if the background was black.  In the former case, all
screen activity remains continuously viewable.  In the latter, the
display updates every five seconds.  In both cases the display blanks
completely after a while.  If you tell the saver not to reserve the
extra memory, it inverts (white->black->white) periodically without
going blank.

When the "Watch modem" switch is set to "Port", the saver monitors the
MFP (ST) serial port and resets whenever it sees activity there, as if
a key had been pressed.  When set to "Buffer", it watches the serial
input buffer instead.  Experiment for best results depending on what
ports and programs you use.

The "Init delay" slider sets how long, in minutes, the saver waits
before dimming the display.  "Dim factor" sets how long it stays in
the dimmed state before going blank, and is multiplied by the delay
value.  For example, if you set initial delay to 10 and dim factor to
5, the screen will go dim after 10 minutes of no input, and blank out
50 minutes later.


 Function key debounce
 =====================

When a shift key is held down and two other adjacent keys are pressed
together, many Atari keyboards tend to erroneously report a shift-F1
or shift-F3, in addition to one or both of the keys actually pressed. 
If you've never noticed, it may be that you are an exceptionally
careful typist, or none of your software does anything interesting
when you press shift-F1 or shift-F3 anyway.  In any case, the debounce
feature effectively cures the glitch.


 R-hold screen after prg
 =======================

This feature is intended for reading the output of a program run from
the desktop when it was designed to run from a command line shell.

You know the feeling.  You run an unfamiliar program, it prints a
screen full of something which immediately disappears, and you're back
at the desktop.  You wonder if there's a command line option you can
send to make the program wait for a keypress before exiting, but of
course that's part of the information you aren't fast enough to read. 
So you run it over and over, vainly trying to freeze the screen by
hitting control-S or alt-Help at just the right millisecond.

If the R-hold option of SilkMouse is active, each application checks
the status of the right mouse button when terminating.  If it is not
being pressed, the application exits normally; otherwise the screen
remains visible in whatever state the application left it, until you
release the button.  You can also lock the screen and free your hands
by clicking the left button while holding the right one down.  Then
you can release both buttons, and the system will stay frozen until
you click again with the right button.


 Parting words
 =============

SilkMouse may be freely distributed as long as it is unaltered and
accompanied by this text file.

Up to version 3.0, SilkMouse was a shareware product with a $10 price
tag.  It was sufficiently popular to pay for my first ST system. 
Since then, a dwindling Atari market and my own improved financial
circumstances persuaded me to make SilkMouse freeware; I still accept
voluntary payments, but everyone is free from obligation.  Anyone who
still wishes to contribute may do so with a check payable to Mark
Slagell (not SilkWare--I've closed that account) and mailed to the
address below.

Bug reports, suggestions, and other comments are all welcome.

Mark Slagell  (sluggo@ames.net)
3716 Ross Road
Ames, IA  50014
USA
