notthecheatr Fader Object

This is a fader object for anyone who wants one, useful for very simple game effects and quite
customizable.  It gives you a smooth fade via Put Alpha blending mode, but it is versatile
enough to allow you to fade between solid colours and images, images and solid colours, or between two
images or two solid colours.

----------Usage----------
Including the module with the fader object is the first thing to do;  you also need to
include the proper namespace that it's contained in, "ntc.specialfx".

    #Include "fader.bas"
    Using ntc.specialfx

After that, you need to create a fader object

    Dim myFader As fader


Because the fader normally creates internal image buffers, you must enter a graphical screenmode beforehand.  This
is logical anyways if you're fading between images, since you'll need to create your own images as well (you
can't create images until you enter a graphical screenmode).

Once you've done this, you may load any images you want to fade between, then start the fade.
There are four fading subs, one for each possible fade method:

  myFader.fadeCtoC - Fade between two solid colours
  myFader.fadeCtoI - Fade from a colour into an image
  myFader.fadeItoC - Fade from an image into a colour
  myFader.fadeItoI - Fade from an image into an image

All of them have approximately the same parameters, although of course slightly different.  The first is the
origin point, either an FB.Image Ptr if you're fading from an image or a uInteger if you're fading from a solid colour.
The second is the finish point, either an FB.Image Ptr if you're fading to an image or a uInteger if you're
fading to a solid colour.  All parameters after that are optional.

For example,

    myFader.fadeCtoC(0, &hffffff)

simply fades from black to white.  Obviously, the numbers can be variables and one or both may be FB.Image Ptrs
depending on the method you use to fade (make sure you use the correct method, or else you'll crash!)


However, those methods only start a fade.  Because the fader object is designed to be used in loops, for example
in game loops, it has a method which you should call within a loop.  This method will update the screen for you,
performing the next "step" in the smooth fade.  The object has a property called "done" that will return a non-zero
value if the object has finished the fade.  Here's an example of a loop:

    Do
      myFader.update()
    Loop Until myFader.done <> 0

After the loop, if you wish to conserve space, you may call

    myFader.finish()

which destroys any image buffers used internally (without destroying the image buffers you passed to it originally).
If you don't do this, you're OK;  it will automatically be called when the object is destroyed, usually at the
end of the program.

Finally, there is the property myFader.ticks.  This tells how many ticks have gone by, or basically, how many
times you've called the method update().  This way, if you wish to you may stop the fade midway by waiting for
a certain value, instead of waiting for the property done to be nonzero.


There are some optional parameters to the fade*to* methods, after the first two listed before.  They are all
the same;  they follow below in the order they are used, with the name, type, default value, and description.

interval As Integer = 1 - This is the interval which the fade uses.  The alpha value used by the drawing routine
  is changed each time you use update().  The default means it's a very smooth fade, starting (by default) at 0
  and encompassing all values in between.  If you increase it to 2, it will fade more quickly but a little less
  smoothly.  However, you don't really notice the change in smoothness unless you go really high.  Its mainly
  speed here.  You can also set it to a negative value, in which case it will fade down.  This is actually about
  equivalent to simply swapping the items being faded and setting interval positive.  For example, if you fade
  from solid red to solid blue with interval -3, it's pretty much the same as fading from solid blue to solid red
  with interval 3.  The only difference would be if you modify the initAlpha value.

initAlpha As uInteger = 0 - This is the initial alpha value for the fader to use;  normally it starts at 0, unless
  interval is negative in which case its default value is 255.  If you change it, it will start the fade already
  midway through.  This may be useful for somethings or not, but that's what it does.

target As FB.Image Ptr = 0 - This is the target, the place being drawn to.  It can be an FB.Image Ptr, but more
  likely it will simply be the screen, which is why its default  value is 0.  If you do want to draw to an
  image buffer instead, you'll of course have to pass a pointer to a valid image buffer.