MRI 30.8.1997


Fading howto
------------

Fading in hi-color modes is very different from 8 bit modes.

 * In 8 bit modes we can just modify the 768 byte palette and the colors
   on the screen will change automagically.

 * In hi-color modes we actually have to modify the pixels on the 
   screen because we don't have any palette. This means that we must
   continuesly copy new data to the screen if we e.g. want a smooth
   fade-out, i.e. the effect must be running.

The good thing with hi-color is that we can fade image <-> effect instead
of just color <-> effect as in 8 bit modes.

Use the following scheme for fading (note, this is "pseudo code"):

 Fade-in:
            xxx xxx  InitializeEffect
            xxx xxx  InitializeFading  in
            002 000  RunEffect

 Fade-out:
            xxx xxx  InitializeEffect
            005 050  RunEffect  
            xxx xxx  InitializeFading  out
            006 000  RunEffect  
            xxx xxx  SetScreen

     Note! After a fade-out we should set the screen to the same value
           we expected the fading to end at. This is because the fading
           might not have reached the end before the effect stopped.
           (These things depends on how fast a machine we are running on
           and what framerate the video card runs at.)

     Note! The fading WILL STAY ON after a fade-out. This could lead
           to problems if you don't want to do a fade-in right after.
           In this case you can turn fading off by doing a 1 frame
           fade-in at the start of the next effect. E.g.

              xxx xxx InitColorFade  00 00 00  1 in



Color <-> effect fading
-----------------------

    xxx xxx  InitColorFade  R G B  frames  dir

        R,G,B   - [0...63] color 
        frames  - fade this many frames
        dir     - fade direction: IN, OUT or HOLD
                  IN   - fade from color -> effect
                  OUT  - fade from effect -> color
                  HOLD - just fill screen with color



Image <-> effect fading
-----------------------

This is actually cross-fading of two images where one of them happens
to be the effect.

    xxx xxx  InitPcxFade   handle  frames  dir

        handle  - handle to image previosly loaded with LoadPcx
        frames  - fade this many frames
        dir     - fade direction: IN, OUT or HOLD
                  IN   - fade from image -> effect
                  OUT  - fade from effect -> image
                  HOLD - just copy image to screen

    Read more about the Pcx commands in SCRIPT.TXT



Examples
--------

Example 1.  Fade in and out to black.

    xxx xxx   InitAnim       efu.ini  efu.3ds
    002 000   WaitSYNC
    xxx xxx   InitColorFade  00 00 00  50  in
    004 050   DoAnim         0 30 0.5 Camera01 -
    xxx xxx   InitColorFade  00 00 00  50  out
    005 000   DoAnim         - - - - -
    xxx xxx   ExitAnim
    xxx xxx   FillSCR        00 00 00


Example 2.  Fade in with GREET.PCX and out with ENDING.PCX.

    xxx xxx   LoadPcx        0  greet.pcx 
    xxx xxx   LoadPcx        1  ending.pcx 
    xxx xxx   InitAnim       efu.ini  efu.3ds
    002 000   WaitSYNC
    xxx xxx   InitPcxFade    0  50  in
    004 050   DoAnim         0  30  0.5  Camera01 -
    xxx xxx   InitPcxFade    1  50  out
    005 000   DoAnim         -   -   -    -       -
    xxx xxx   ExitAnim
    xxx xxx   DisplayPcx     1  waitframe
    xxx xxx   FreePcx        0
    xxx xxx   FreePcx        1

And of cource you can fade in with a color and out with an image
and vice versa.

The PCX (or PCY) images can be any size as LoadPcx will stretch them to the
current screen size.

