notthecheatr Dissolver Object

This is a dissolver effect object.  It's very similar to the fader object, except that the effect is a dissolve
rather than a fade.  A little bit more complicated code, but just as easy to use.  It's also very versatile,
allowing you to specify a number of useful parameters to it.  Like the fader, you may dissolve between solid colours
and images, images and solid colours, or between two images or two solid colours.

----------Usage----------
Start by including the module and using the namespace:

    #Include "dissolver.bas"
    Using ntc.specialfx

Then create a dissolver object

  Dim myDissolver As dissolver


Like all the other effect objects, you need to enter a screenmode before you can do anything else.  This
is logical, since you'll likely be dissolving between different images (you're exempt if you only dissolve between
two different colours, but where's the fun in that?)

Once you're in a valid screenmode and you've loaded any images you want to dissolve between, you can use any
of the four methods for dissolving.  They correspond to the four methods of fading, and the usage is pretty
obvious:

  myDissolver.dissolveCtoC - Dissolve between two solid colours
  myDissolver.dissolveCtoI - Dissolve from a colour into an image
  myDissolver.dissolveItoC - Dissolve from an image into a colour
  myDissolver.dissolveItoI - Dissolve from an image into an image

As with the fader, the first two arguments are, in order, the origin and the destiny (starting and finishing
points) - the type will be uInteger for colour or FB.Image Ptr, depending on which method you use.  All other
parameters are optional and will be covered later.

Like all my other effect objects, you use a loop:

    Do
      myDissolver.update()
    Loop Until myDissolver.done()

The dissolver works by placing random blocks from the destiny image or colour on top of the origin image;
based on probability, it knows how many times it has to do this before the dissolve is mostly done, so once it's
done it that many times it simply draws the entire destiny image on top of the origin, to cover any pixels/blocks
that were missed.  Then it marks itself done, at which point the loop will quit.  If for some reason you should
wish to quit early, you can also check the property ticks, which returns the number of times you've called
the update() method so far.  Then you could stop at a specific update() rather than when the object tells
you it's done.


Once finished, you may wish to call the finish method

    myDissolver.finish()

which destroys all temporary buffers, to save memory.  If you don't, that's OK;  it will be called when the
object is destroyed.


So what about the extra parameters to dissolve*to*?  They follow below, in order with their name, type,
default value, and description.

blockSize As uInteger = 1 - The dissolver works by getting random blocks from the destiny image or colour
  and placing them on top of the origin image or colour.  This lets you specify the size of blocks you want;
  larger blocks will fill up more quickly but will look blockier, while smaller blocks will be somewhat smoother
  but slower.  The blocks used are simply square blocks of the size blockSize X blockSize.

blocksPerTick As uInteger = 1 - This specifies how many blocks to do per tick.  Normally only one new block is
  added per time you call update(), but you can change this.  It won't have a huge effect, but it will help to
  speed things up a bit.

stopThreshold As Single = 1 - This lets you fine-tune the number of ticks the dissolver object will go through
  before marking itself done.  A special formula is used, based on the size of the width and height of the
  threshold and the blockSize and blocksPerTick.  The formula seems to work pretty well, but it isn't perfect.
  In the end it's multiplied by stopThreshold, so if you leave this value at 1 no change is made.  If you set it
  to less than 1, the dissolve will finish sooner than normal.  If you set it above 1, the dissolve will go on
  longer than usual.  This can be used to make the effect as convincing as possible.

iMode As Integer = 0 - This is ONLY availible when dissolving TO an image (using dissolveCtoI or dissolveItoI).
  It specifies the drawing mode of the destiny image.  The default value, 0, simply draws using PSet.  1
  draws using Trans (if you have transparent areas in your image specified via &hff00ff) and 2 draws using
  Alpha (if you have alpha channels in your image.  In this case, of course, only the parts of the destiny that
  are opaque or partially opaque are actually dissolved;  the parts that aren't still show the origin image or
  colour below.

target As FB.Image Ptr = 0 - This specifies the target to draw to;  the default value of 0 simply draws to the
  screen, but any other value must be a pointer to a valid image buffer.