MRI 20.5.1998


DSYS color filters
------------------

The color filters will read each pixel from the frame buffer, split them
up into their components Red, Green and Blue, then reduce the intensity
of some or all of the components. The intensity is reduced accordingly to
the intensity in a grayscale bitmap (the shade filter bitmap). In other
words, the bitmap specify where on the framebuffer to apply the filter and
the strength at that position.

The bitmap can be smoothly animated.

The following filter types are available: RGB, RG, GB, RB, R, G, B
I.e. any combination. RGB means that all components will be shaded,
R means that only the Red components will be shaded, etc. 

There are also 2 filter types that only swaps the RGB components
without shading them and 4 filter types that inverts the specified
components.

The filter is applied on the framebuffer using the PostProcessing
functions.


Script functions
----------------

  xxx xxx  InitShadeFilter
        Initializes the filters.

  xxx xxx  ExitShadeFilter
        Frees up resources used by the filters and filter bitmaps.

  xxx xxx  LoadShadeFilterPcx  handle  filename
        Load a grayscale filter bitmap to this handle. Bitmap can be
        any size as it is automatically scaled to the current
        screen size.

  xxx xxx  SetShadeFilter  postfunc  handle  type
        Start using a filter. This must be done after InitAnim
        postfuc - postprocessing function number
        handle  - filter bitmap handle
        type    - filter type: RGB, RG, GB, RB, R, G, B, swapBGR, swapRBG,
                               invertRGB, invertR, invertG, invertB

        Note! If the filter type is any of the swap*** or invert*** the
              handle should be set to -1 as no shade bitmap is needed.

  xxx xxx  SetFilterBitmapLoop  handle  frames  sequence
        Setup an animated bitmap as a sequence of the already
        loaded bitmaps.
        handle   - filter bitmap handle to put the animated filter on
        frames   - frames per bitmap in the animation sequence (speed)
        sequence - a string with the bitmap sequence (their handles).
                   0...9 and A...F

  xxx xxx  ClearFilterBitmapLoop  handle
        Stop and remove a filter bitmap loop. Always stop the loop if you
        don't need the loop. Otherwice you will waste CPU power.

        Note! You can change the filter type with SetShadeFilter while
              a bitmap loop is running. You can also change the loop on
              the fly.


A filter can be deactivated by removing the postprocsessing function it was
installed on. E.g.

  xxx xxx  SetShadeFilter  3  0 RGB
  xxx xxx  RemovePostDraw  3


Example.

  xxx xxx  InitShadeFilter
  xxx xxx  LoadShadeFilterPcx     0 filter/filt00.pcx
  xxx xxx  LoadShadeFilterPcx     1 filter/filt01.pcx
  xxx xxx  LoadShadeFilterPcx     2 filter/filt02.pcx
  xxx xxx  InitAnim               ...

# Apply static filters
  xxx xxx  SetShadeFilter         0 10 RGB
  001 000  DoAnim                 ...
  xxx xxx  SetShadeFilter         1 10 RGB
  002 000  DoAnim                 - - - - -
  xxx xxx  SetShadeFilter         2 10 RGB
  003 000  DoAnim                 - - - - -

# Start a animated filter loop on handle 5
  xxx xxx  SetFilterBitmapLoop    5 60 01202102012
  004 000  DoAnim                 - - - - -

# Swap filter type, loop is still running
  xxx xxx  SetShadeFilter         5 10 R
  006 000  DoAnim                 - - - - -
  xxx xxx  ClearFilterBitmapLoop  5
  xxx xxx  SetShadeFilter         0 -1 swapRGB
  007 000  DoAnim                 - - - - -

  xxx xxx  ExitAnim
  xxx xxx  ExitShadeFilter


