@DATABASE WinnerEVD.guide
@AUTHOR "Niels Knoop"
@(C) "Copyright © 1998 Niels Knoop"
@$VER: WinnerEVD.guide 1.0 (15.5.98)

@NODE Main "WinnerEVD"

                              @{U}WinnerEVD 1.0@{UU}

                   ShapeShifter External Video Driver
                     with Intuition window display
                           © 1998 Niels Knoop
                                @{U}Mailware@{UU}

                             @{" Introduction  " LINK Introduction}
                             @{" Features      " LINK Features}
                             @{" Requirements  " LINK Requirements}

                             @{" Installation  " LINK Installation}
                             @{" Configuration " LINK Configuration}
                             @{" Options       " LINK Options}

                             @{" Copyright     " LINK Copyright}
                             @{" Credits       " LINK Credits}
                             @{" Author        " LINK Author}
@ENDNODE Main


@NODE Introduction "WinnerEVD"

@{U}Introduction@{UU}

WinnerEVD, as the first syllable of its name suggests, is a ShapeShifter
driver which shows the Mac display inside a window. It is designed as an
universal driver which supports all color depths and nearly all display
devices including OCS, ECS and AGA, but works best on graphics cards.

Why use an external driver when ShapeShifter already comes with built-in
support for Amiga window displays? Well, as its name may also suggest,
WinnerEVD does it better. Compared to the internal driver it wins both the
feature and the performance contest.

However, in terms of speed WinnerEVD does not and cannot compete with
drivers which use their own screens. (The only exceptions are 1-bit
WinnerEVD displays on graphics cards, because in this case the refresh
can be accelerated by the blitter on the card.) If performance is your
only concern, I suggest that you use TurboEVD (on OCS/ECS/AGA) or
CardTrickEVD (on graphics cards) instead.
@ENDNODE


@NODE Features "WinnerEVD"

@{U}Features@{UU}

@{"  " LINK Window } Display inside an Intuition window
@{"  " LINK Depths } Mac displays with 1, 2, 4, 8, 15, or 24 bits per pixel
@{"  " LINK Blocks } Piecemeal refresh to avoid blocking other tasks
@{"  " LINK MMU    } MMU-aided refresh to reduce the refresh overhead
@ENDNODE


@NODE Window "WinnerEVD Features"

@{U}Display inside an Intuition window@{UU}

WinnerEVD shows the Mac display inside a normal Intuition window on the
Workbench or any other public screen. The refresh is accomplished in a
system-friendly way using OS functions and, if available, some extended
features of CyberGraphX and/or Picasso96.

It should be noted that due to limitations of the current EVD interface
a few minor patches are necessary to make this kind of driver possible.
WinnerEVD automatically applies them to ShapeShifter's code in memory at
runtime. Hopefully future versions of ShapeShifter will extend the EVD
interface to make this little stunt superfluous.
@ENDNODE


@NODE Depths "WinnerEVD Features"

@{U}Display modes@{UU}

WinnerEVD supports all Mac display modes you can use with ShapeShifter:
1, 2, 4 and 8 bit should work on any screen with a sufficient number of
colors, 15 and 24 bit require a graphics card.
@ENDNODE


@NODE Blocks "WinnerEVD Features"

@{U}Piecemeal refresh@{UU}

For the biggest part of the actual refresh WinnerEVD uses functions of the
OS, CyberGraphX or Picasso96. Depending on the way they are implemented
these routines can temporarily block other system activities. The effects
like jerky mouse movement can be observed when using a 24-bit Amiga window
display on a hi- or truecolor screen with ShapeShifter's internal driver.
To avoid such behaviour WinnerEVD splits the display into a number of
blocks with constant size and refreshes them seperately.
@ENDNODE


@NODE MMU "WinnerEVD Features"

@{U}MMU-aided refresh@{UU}

MMU-aided refresh means to use the MMU to watch over the refresh buffer
and keep track of which parts of it are written to by the emulated Mac.
The goal is to update only those parts of the display which have actually
changed since the last refresh cycle. This way the emulation can run at
almost full speed as long as nothing much happens on the display.

WinnerEVD's MMU routines require a 68040 or 68060 CPU and support both
4K and 8K pagesize. The MMU tables must already be set up and enabled which
is usually done by the 68040.library at the time SetPatch is executed.
@ENDNODE


@NODE Requirements "WinnerEVD"

@{U}Requirements@{UU}

In order to run WinnerEVD you need:

- An Amiga
- OS 3.0 or later
- ShapeShifter version 3.2 to 3.9

Optional, but highly recommended:

- A 68040 or 68060 processor with MMU for MMU-aided refresh
- NewWPA8 to accelerate the display on Amiga bitmap screens
- A graphics card to improve the display in every way
- CyberGraphX or compatible driver for 24-bit displays
- Picasso96 for 15-bit displays and improved color fidelity
@ENDNODE


@NODE Installation "WinnerEVD"

@{U}Installation@{UU}

Simply copy WinnerEVD into the "Video Drivers" drawer inside your
ShapeShifter drawer.

If you do not have a graphics card you should install NewWPA8. This
little patch replaces some chunky pixel functions of graphics.library
with optimized versions and accelerates WinnerEVD's refresh on a big
scale. You can find it on Aminet in the util/boot directory. Refer to
its documentation for further details.
@ENDNODE


@NODE Configuration "WinnerEVD"

@{U}Configuration@{UU}

Start ShapeShifter and open the @{B}Graphics Settings@{UB} window. Select @{B}1 monitor@{UB},
set @{B}Screen type@{UB} to @{B}External@{UB} and choose WinnerEVD as @{B}External driver@{UB}.

Regarding the @{B}Color depth@{UB} there are some limitations to consider:

- 1/2/4/8-bit displays work on any native or graphics card screen. The
  driver has to share the palette of pens with other applications. If the
  screen runs out of free pens, occupied ones have to be recycled which
  injures the color fidelity. I recommend the following minimum depths for
  the public screen: 4 colors for 1-bit, 8 colors (with at least one extra
  grey tone as in the MagicWB palette) for 2-bit, 32 colors for 4-bit and
  256 colors for 8-bit displays. Graphics card owners should always use
  256 colors. When using a hi- or truecolor screen under Picasso96 1.37 or
  later, WinnerEVD can bypass the screen's palette and thus the colors are
  always accurate.

- 15-bit displays only work on hi- or truecolor Picasso96 screens. Hicolor
  screens should be preferred because they use less bandwidth.

- 24-bit displays require CyberGraphX or a compatible driver and using them
  obviously only makes sense on a truecolor screen.

The @{B}Screen mode@{UB} selection has no meaning with WinnerEVD, but provides a
convenient way to set the display dimensions which can otherwise be entered
manually next to @{B}Size@{UB}. Of course they should be adjusted to fit on the
screen because otherwise the display will be clipped.

Selecting a @{B}Refresh rate@{UB} value basically means to find the best compromise
between display update speed and emulation performance. Lower values will
improve the visual impression, but leave less power for the emulated Mac.
With simple refresh this loss is permanent while with @{"MMU-aided refresh" LINK MMU} the
slowdown only occurs on actual graphical operations, making it possible to
use the minimum refresh rate of 1.

With WinnerEVD you should always select the @{B}Amiga mouse pointer@{UB}. If you use
ShapeShifter's own software cursor, the Amiga mousepointer will be blanked,
but still be active and moving independantly; unintentional mouseclicks
outside the emulation window will deactivate it or have other unpleasant
effects.

The state of the check box @{B}Black border@{UB} has no effect with the EVD. The
same is true for @{B}Refresh always@{UB} and @{B}MMU refresh@{UB}. WinnerEVD always uses
refresh and automatically utilizes the MMU if possible.

In ShapeShifter's @{B}Memory Settings@{UB}, it's usually not a good idea to select
the @{B}Largest free block@{UB} option, because it might leave only slower memory
or none at all for WinnerEVD's refresh buffers. You should disable it
and enter a reduced @{B}Mac memory@{UB} value instead.

If you often use different settings for various EVDs and screenmodes, I
suggest to save them into individual projects using @{B}Save As...@{UB} from the
main menu.

For more information about ShapeShifter's settings please refer to the
ShapeShifter manual.
@ENDNODE


@NODE Options "WinnerEVD"

@{U}Options@{UU}

WinnerEVD provides a number of options to control some of its features.
Their settings are stored as an argument string in the environment variable
ENV:WinnerEVD.config. If you want to use certain options, create or edit
that file and enter all the options and eventual values in a single line
separated with spaces.

For example, to set some options from an Amiga shell window you could type:
Echo >ENV:WinnerEVD.config "PUBSCREEN=MyScreen NOMMU"
To make your changes permanent, also copy the file over to ENVARC:.

The options are:

@{"  " LINK PUBSCREEN } PUBSCREEN
@{"  " LINK NOMMU     } NOMMU
@ENDNODE


@NODE PUBSCREEN "WinnerEVD Options"

@{U}PUBSCREEN@{UU}

By default, WinnerEVD opens its window on the default public screen which
is usually the Workbench screen. If you prefer another screen as host of
your WinnerEVD display, you can either use one of the numerous pubscreen
managers to change the default public screen or directly tell WinnerEVD
the name of your favorite public screen. To do so, put the PUBSCREEN option
and the public screen name into the configuration string, for example
"PUBSCREEN=MyScreen". If WinnerEVD cannot find this screen, it will fall
back on the default screen.
@ENDNODE


@NODE NOMMU "WinnerEVD Options"

@{U}NOMMU@{UU}

If this switch option is activated by adding its name to the configuration
string, WinnerEVD will not use the @{"MMU" LINK MMU} to reduce the refresh overhead.
This is meant for test purposes only; it should never be necessary to use
it unless you have problems with your MMU.
@ENDNODE


@NODE Copyright "WinnerEVD"

@{U}Copyright@{UU}

WinnerEVD is Mailware. If you like and use it, please send @{"me" LINK Author} some mail
of any kind. A few lines of e-mail will do, but I would prefer paperwork,
i.e. nice postcards, letters, parcels... :-)

Program and documentation are freely distributable as long as the archive
remains complete and unchanged.

This software is provided "as is" without warranty of any kind, either
expressed or implied. You use it entirely at your own risk.
@ENDNODE


@NODE Credits "WinnerEVD"

@{U}Credits@{UU}

I would like to thank the following people:

- Francesco Doro for encouragement, advice and beta-testing
- Christian Bauer for ShapeShifter and its EVD interface
- Frank Mariak & Thomas Sontowski for CyberGraphX
- Tobias Abt & Alexander Kneer for Picasso96
- Frank Wille for PhxAss and PhxLnk
- Michael van Elst for NewWPA8
@ENDNODE


@NODE Author "WinnerEVD"

@{U}Author@{UU}

Send comments, questions, bugreports or whatever to:

  Niels Knoop
  Hainstr. 21a
  D-61476 Kronberg
  Germany

E-mail:

  niels@rbg.informatik.tu-darmstadt.de
@ENDNODE