                                  Introduction

****************************************************************************
----------------------------------------------------------------------------

AniSprite is a multi layer sprite animation library for Microsoft Windows
3.1 and Windows 95.


Features

Besides the basic features, like flicker free / multi layer animations,
AniSprite supports:



  * alpha blending
  * back shining
  * image fading
  * multiple animation areas
  * 256 colour animation
  * unlimited number of sprites
  * speedy GDI free implementation (except for the screen blitting)
  * 16 bit and 32 bit implementation
  * source availability
  * Windows DLL interface plus stubs for C/C++/Visual basic
                                    Glossary

****************************************************************************
----------------------------------------------------------------------------

Action               A sprite action is one of the following:
                       * movement
                       * appearance change
                       * visibility change

Alpha blending       Alpha blending or alpha -channel compositing is a tech-
                     nique to blend two images into one destination image.
                     The destination image is a weighted means of the two
                     input images.

Back shining         Back shining is a kind of image blending. The destina-
                     tion pixel either equals the foreground pixel, or the
                     background pixel with adjusted brightness.

Board                Animation area defined as a visible part of a bitmap.
                     A board contains zero or more layers, each with one or
                     more sprites.

Cutout mask          A binary opaque/transparent mask (see next chapter on
                     Masks).

DIB format           Device Independent Bitmap format.

Layer                A layer on a board represents a relative z-order level.
                     Layer zero is the lowest z-order level. Each layer may
                     contain a number of sprites, and has consequently as
                     many z-order levels as sprites. However the z-ordering
                     of the sprites within a layer is indeterminate.

                     To define a z-ordering among a set of sprites, the
                     sprites must be assigned to a set of ordered layers on
                     the board.

Palette              Lookup table with a limited number of RGB colours.
                     AniSprite always works with 256 colour images and 256
                     colour palettes. 256 colour images always use palettes
                     and the image elements contain indexes in the palette.
                     For a discussion on how to use palettes in a MS-Windows
                     environment see ..)
Slot
                     The period in which sprite actions and board replacements
                     are carried out before the board is repainted on the
                     screen. In other words a slot is the time period between
                     two board paint actions.


Sprite               Semi transparent graphic object. To come into action a
                     sprite must be assigned to a board layer.
                                      Masks

****************************************************************************
----------------------------------------------------------------------------

When displaying a somewhat transparent foreground image on a background
image, a mask is needed to describe the mixing of both images. The mask
itself has the same dimensions as the foreground image and tells for each
pixel at the destination location how to mix foreground and background
colour. AniSprite supports three mask types: cutout masks, shine masks and
alpha masks. The mask image data layout always conforms to the 8-bpp DIB
format, independent of the mask type.


Cutout mask

A cutout mask is a binary mask. A pixel in the foreground image is either
opaque or transparent. From the destination pixel point of view: the pixel
colour is either the foreground image colour or the background image colour.

In AniSprite mask colour value 0 means opaque and 255 means transparent.


Shine mask

A shine mask is a multi value mask to enable back shining. A pixel in the
foreground image is either opaque or transparent. If it is transparent the
mask describes the brightness of the background image at the destination
pixel location.

This mask type can be used to introduce shadow and shine for 3d suggestion.

In AniSprite mask colour value 0 means opaque and 255 means transparent.
Values in between indicate a certain grade of shade or extra brightness of
the background image colour. The actual brightness colour grades must be
supplied by the user.
Alpha mask
An alpha mask is the most general multi value mask to enable alpha blending.
Any destination pixel colour is a mixture of foreground image and background
image. From the foreground image point of view: any pixel is more or less
transparent. One extreme is a complete opaque pixel and the other is a
complete transparent pixel. A cutout mask is therefore the simplest alpha
mask.

In AniSprite mask colour value 0 means completely opaque and 255 means com-
pletely transparent. All values in between gradually mix between foreground
and background, however the actual graded colours must be supplied by the
user.
                                Using AniSprite

****************************************************************************
----------------------------------------------------------------------------



How to?


Set up an animation

  * load the board image
       Load bitmap in DIB format including the bitmap info header.

  * create a palette
       Use the bitmap info palette entries to create a palette.

  * create a board
       Given the bitmap and bitmap info you can create a board. If not all of
       the bitmap is to be involved in the animation the visible board can be
       reduced to a part of the bitmap. At this moment the board installs its
       masking capabilities, that can not be extended afterwards.

  * enhance board mask capabilities
       When the board is created to support alpha blending and / or back
       shining, you may now create (or load) and install alpha levels and /
       or brightness levels.

  * load sprite bitmaps
       Load bitmap in DIB format including the bitmap info header. The bitmap
       palette should be the same as the board bitmap palette, otherwise you
       must remap the bitmap so that is does fit to the board palette.

  * load or create sprite masks
       Load mask image from disk or create it from the image using transpar-
       ent colours. In the latter case as_CreateMask does the job.

  * create sprites
       Use as_Create to create the sprite.

  * assign sprites to board layers
       To come into action a sprite must be assigned to a board layer. Use
       as_Assign(Board, LAYER_NUMBER, Sprite).

  * process the palette event messages
       In 256 colour mode the application has to set its own palette before
       doing any graphical operations in a screen device context. The event
       messages WM_QUERYNEWPALETTE and WM_PALETTECHANGED indicate that the
       application has to set its palette if it is using one (see MS-Windows
       documentation).

     ----------------------------------------------------------------------

         case WM_QUERYNEWPALETTE:
             hDC = GetDC(hWnd);
             hOldPal = SelectPalette(hDC, hPalette, FALSE);
             RealizePalette(hDC);
             SelectPalette(hDC, hOldPal, TRUE);
             if (RealizePalette(hDC)) {
                 InvalidateRect(hWnd, NULL, FALSE);
             } /* endif */
             ReleaseDC(hWnd, hDC);
             return(TRUE);

         case WM_PALETTECHANGED:
             if ((HWND) wParam != hWnd) {
                 hDC = GetDC(hWnd);
                 hOldPal = SelectPalette(hDC, hPalette, FALSE);
                 if (RealizePalette(hDC)) {
                     InvalidateRect(hWnd, NULL, FALSE);
                 } /* endif */
                 SelectPalette(hDC, hOldPal, TRUE);
                 RealizePalette(hDC);
                 ReleaseDC(hWnd, hDC);
             } /* endif */
             break;



     ----------------------------------------------------------------------
     Figure 1: Processing the palette event messages

* process the paint event message
     To keep the window appearance up with the current board situation
     the WM_PAINT message must be processed. Since it is up to the window
     system to decide which parts of the window have to be repainted,
     AniSprite has to paint all of the board (PaintAll == TRUE).

                                  continued
       ----------------------------------------------------------------------

           case WM_PAINT:
               hDC = BeginPaint(hWnd, &ps);
               hOldPal = SelectPalette(hDC, hPalette, FALSE);
               RealizePalette(hDC);
               as_PaintBoard(hDC, Board, 0, 0, TRUE); /* PaintAll == TRUE */
               SelectPalette(hDC, hOldPal, TRUE);
               RealizePalette(hDC);
               EndPaint(hWnd, &ps);
               break;



       ----------------------------------------------------------------------
       Figure 2: Processing the WM_PAINT event message



Clean up an animation

  * abort sprite assignments
       Abort the board layer assignment with as_Assign(Board, -1, Sprite).

  * delete sprites
       If the sprite is no longer assigned to a board it must be deleted with
       a call to as_Delete(&Sprite).

  * free up the sprite image and mask memory
       It depends on how the sprite image and mask is retrieved, how the
       memory resources must be freed up. If as_CreateMask was used to create
       the mask, then it must be freed with as_DeleteResource.

  * free up possible alpha levels and / or shine levels
       In general not all alpha levels and brightness levels are unique. It
       is therefore more comfortable to store them in an array at creation
       time and delete all levels in this array with as_DeleteResource.

  * delete the board
       The board is deleted by one call to as_DeleteBoard(&Board). At this
       time there should no sprites left assigned to the board.

  * free the board image
       Again this depends on how the bitmap image was loaded from disk or
       created in memory.
Fade an image
With AniSprites alpha blending feature, sprites can be faded in and out as
described in the following steps.

  * set up an animation
       Set up the animation as described in the previous section. To enable
       fading the board must be configured to support alpha blending. While
       fading out the foreground image vanishes in the background and while
       fading in the background image vanishes where the foreground image
       shows up. In both cases one of the images is gradually emphasized with
       respect to the other.

       When the board is setup for alpha blending, it only has to trivial
       alpha levels. Because we want a number of grades, we must install a
       number of alpha levels in the board.

       Let's say, we want LEVELS intermediate levels.

       ----------------------------------------------------------------------

               step = 256 / (LEVELS + 1);
               prev_index = index = step / 2;
               for (i = 0; i < LEVELS; i++) {
                   Level = as_CreateAlphaLevel(lpPal,
                                                (double) (i + 1) / (LEVELS +
       1));
                   for (j = prev_index; j < index; j++) {
                       as_SetBoardValuePtr(Board,
                                            AS_VALUEPTR_ALPHA_LEVEL, j,
       Level);
                   } /* endfor */
                   prev_index = index;
               } /* endfor */

               index = 256 - step / 2;
               for (j = prev_index; j < index; j++) {
                   as_SetBoardValuePtr(RoadBoard, AS_VALUEPTR_ALPHA_LEVEL, j,
                                        AlphaTable[i - 1]);
               } /* endfor */



       ----------------------------------------------------------------------
     Figure 3: Installing alpha levels for fading

     The initial sprite mask should be 0 for the opaque parts when fading
     out or 255 when fading in. To make the mask adjustment easier, you
     better initialise the opaque parts with say 254, so you can test for
     non-transparent pixels (mask value != 255).

* retrieve the sprite mask
     The sprite mask can be retrieved with as_GetValuePtr and parameter
     AS_VALUEPTR_MASKBITS or you may store the mask pointer when you create
     the sprite.

* adjust the mask
     Increase or decrease the mask pixels with a certain amount. Typically
     this would be  256(LEVELS+1).

* animate the sprite with the new mask
     Simply call as_Animate with the new mask (other parameters remain
     unchanged).

* repeat until the sprite is completely transparent or opaque
     A complete transparent mask has all 255 and a complete opaque mask has
     all zeros.
Optimizations
  * Reduce in memory blitting
       When moving and animating in one slot it is better to first hide the
       sprite and show it again afterwards. This is especially true if you
       prevent the sprite from colliding to other sprites or keeping it in a
       box. I this way the sprite makes a number trial moves before settling
       at its definitive place.

  * Reduce memory usage
       There is a number of ways to reduce AniSprites memory usage. The most
       memory consuming is alpha level installation and large scratch areas.

         * minimal board dimensions
             AniSprite creates a scratch area as large as the visible board
             image area. Choose this area as small as possible to reduce the
             scratch area dimensions.

         * minimal number of alpha / brightness levels
             When all alpha levels are uniquely installed, the memory usage
             is 256 times 64 kB is 16 MB! Since the number of palette colours
             is only 256 it is impossible to make really 256 unique alpha
             levels for each palette colour. However the maximum number
             of unique alpha levels per palette entry depends on the other
             palette entries.

             Install a reasonable number of unique alpha levels.

             Brightness levels take only 256 byte per level, so you don't
             have to worry to much about them. Although, if you are really
             pushing the limits, the same holds for brightness levels as for
             alpha levels. Find a reasonable number of unique levels.

         * minimal mask type
             Cutout masks are the cheapest with respect to memory consump-
             tion. Shine masks need brightness levels and alpha masks need
             alpha levels, which take 64 kB each. If you actually need a
             cutout mask then don't use an alpha mask, although it will
             function perfectly well too. If you do not really need alpha
             blending, because back shining will do as well, then use back
             shining.

             Besides the minimal memory usage, in AniSprite the in memory
             blitting for cutout masked sprites is the fastest.
Example
----------------------------------------------------------------------------



long FAR PASCAL WndProc(HWND hWnd, UINT Message, WPARAM wParam, LPARAM
lParam)
{
static ASBOARD Board;
static ASPRITE Sprite;
static HPALETTE hPalette;
static COLORREF crTransColor[] = {PALETTERGB(0xff, 0x00, 0xff)};  /* magenta
*/

    HPALETTE hOldPal;
    PAINTSTRUCT ps;
    HDC hDC;
    LPVOID lpBits, lpMask;
    LPBITMAPINFO lpBitsInfo;

    switch (Message) {

    case WM_CREATE:
         lpBitsInfo = malloc(sizeof(BITMAPINFO) + 256 * sizeof(RGBQUAD));
         lpBits = LoadBitmapBits("backgr.bmp", lpBitsInfo);
         hPalette = MakeDIBPalette(lpBitsInfo);
         as_CreateBoard(&Board, lpBitsInfo, lpBits, NULL, 0);

         lpBits = LoadBitmapBits("sprite.bmp", lpBitsInfo);
         lpMask = as_CreateMask(lpBitsInfo, lpBits, TRUE, crTransColor, 1);
         as_Create(&Sprite,
                   (int) lpBitsInfo->bmiHeader.biWidth,
                   (int) lpBitsInfo->bmiHeader.biHeight,
                   lpMask, AS_MASK_CUTOUT, lpBits, TRUE);

         as_Assign(Board, 0, Sprite);
         as_Move(Sprite, 20, 20);
         as_Show(Sprite, TRUE);

         free(lpBitsInfo);
         break;

    case WM_DESTROY:
                                    continued
     as_Assign(Board, -1, Sprite);

     lpMask = as_GetValuePtr(Sprite, AS_VALUEPTR_MASKBITS);
     lpBits = as_GetValuePtr(Sprite, AS_VALUEPTR_IMAGEBITS);
     as_Delete(&Sprite);
     as_DeleteResource(lpMask);
     free(lpBits);

     lpBits = as_GetBoardValuePtr(Board, AS_VALUEPTR_IMAGEBITS, 0);
     as_DeleteBoard(&Board);
     free(lpBits);
     break;

case WM_PAINT:
     hDC = BeginPaint(hWnd, &ps);
     hOldPal = SelectPalette(hDC, hPalette, FALSE);
     RealizePalette(hDC);
     as_PaintBoard(hDC, Board, 0, 0, TRUE);
     SelectPalette(hDC, hOldPal, TRUE);
     RealizePalette(hDC);
     EndPaint(hWnd, &ps);
     break;

case WM_QUERYNEWPALETTE:
     hDC = GetDC(hWnd);
     hOldPal = SelectPalette(hDC, hPalette, FALSE);
     RealizePalette(hDC);
     SelectPalette(hDC, hOldPal, TRUE);
     if (RealizePalette(hDC)) {
         InvalidateRect(hWnd, NULL, FALSE);
     } /* endif */
     ReleaseDC(hWnd, hDC);
     return(TRUE);

case WM_PALETTECHANGED:
     if ((HWND) wParam != hWnd) {
         hDC = GetDC(hWnd);
         hOldPal = SelectPalette(hDC, hPalette, FALSE);
         if (RealizePalette(hDC)) {
             InvalidateRect(hWnd, NULL, FALSE);
         } /* endif */
         SelectPalette(hDC, hOldPal, TRUE);

                                continued

         RealizePalette(hDC);
         ReleaseDC(hWnd, hDC);

     } /* endif */
         break;

    . .
    } /* endswitch */
}



                                    continued
LPVOID LoadBitmapBits(LPSTR FileName, LPBITMAPINFO bi)

{
    LPVOID lpBits;
    int linesz, file;
    long bitmapsz;

    if ((file = _lopen(FileName, OF_READ  OF_SHARE_DENY_WRITE)) >= 0) {
         _lread(file, &bi->bmiHeader, sizeof(BITMAPINFOHEADER));
         _lread(file, bi->bmiColors, 256 * sizeof(RGBQUAD));
         linesz = (int) (((bi->bmiHeader.biWidth * 8 + 31) & ~31u) >> 3u);
         bitmapsz = bi->bmiHeader.biHeight * linesz;

         if ((lpBits = malloc(bitmapsz)) != NULL) {
             _hread(file, lpBits, bitmapsz);
         } /* endif */

         _lclose(file);
         return(lpBits);
    } /* endif */
    return(NULL);
}

HPALETTE MakeDIBPalette(LPBITMAPINFO bi)
{
    NPLOGPALETTE npPal;
    RGBQUAD far *lpRGB;
    HPALETTE hPalette;
    int i;

    npPal = (NPLOGPALETTE) LocalAlloc(LMEM_FIXED, sizeof(LOGPALETTE) +
                                        256 * sizeof(PALETTEENTRY));
    npPal->palVersion = 0x300;
    npPal->palNumEntries = 256;

    /* get pointer to the color table */
    lpRGB = bi->bmiColors;
    /* copy colors from the color table to the LogPalette structure */
    for (i = 0; i < 256; i++, lpRGB++) {
         npPal->palPalEntry[i].peRed = lpRGB->rgbRed;
         npPal->palPalEntry[i].peGreen = lpRGB->rgbGreen;
         npPal->palPalEntry[i].peBlue = lpRGB->rgbBlue;

                                    continued


        npPal->palPalEntry[i].peFlags = 0;
    } /* endfor */
    hPalette = CreatePalette((LPLOGPALETTE)npPal);
    LocalFree((HANDLE) npPal);
    return (hPalette);
}



----------------------------------------------------------------------------
Figure 4: Minimal example
                               Function reference

****************************************************************************
----------------------------------------------------------------------------

This chapter lists all AniSprite functions and datastructures. To prevent
from naming conflicts with other libraries, functions, constants and types
have the prefix as_, AS_ and AS respectively.

Because AniSprite is a sprite library, we left out the word Sprite in most
function names that concern a sprite. For example: as_Move moves a sprite to
a new position.

Coordinates and rectangles as parameters of AniSprite functions are always
relative to the board background bitmap. There is only one exception to this
rule. The function as_PaintBoard paints the board and its contents at an
arbitrary position.





============================================================================
as_Animate

as_Animate gives the sprite a new appearance. There are no restrictions,
so size and mask type may change too. For efficiency reasons the function
may be supplied with a rectangle defining the part of the image that has
actually changed.



Syntax:      BOOL as_Animate(ASPRITE Sprite,
                             int Width, int Height,
                             LPVOID lpMask, int MaskCode,
                             LPVOID lpImage, BOOL ImageMasked,
                             LPRECT lpInvalidRect)

             Sprite      Identifies the sprite.

             Width,
             Height      Dimensions of the sprite. This must be the real mask
                         and image dimensions.
             lpMask
                         The mask bits in 8-bpp DIB format. When the sprite does
                         not have a mask, (see MaskCode) the lpMask parameter is
                         ignored. AniSprite supports three different masks:


                           * cutout mask
                                Cutout masks have an optimized blit function,
                                if the image bits have been masked out (see
                                ImageMasked parameter).

                           * shine mask

                           * alpha mask

             MaskCode    The MaskCode indicates the type of mask that is
                         supplied. It can be any of the following values:
                           * AS_MASK_NONE(0)
                           * AS_MASK_CUTOUT(1)
                           * AS_MASK_SHINE(2)
                           * AS_MASK_ALPHA(3)

             lpImage     The image bits in 8-bpp DIB format.

             ImageMasked This boolean variable indicates, whether the trans-
                         parent parts of the image have already been masked
                         out.

                         When the supplied mask is a cutout mask and the
                         image has been masked out, AniSprite can speed
                         up the off screen image blitting. In other cases,
                         masking out is useless.

             lpInvalidRect
                         Part of Sprite image that changes as a consequence
                         of the animation. When all of the image changes or
                         if you don't care or don't know, set lpInvalidRect
                         to NULL.

Returns:     If the board does support the image mask type or if the sprite
             does not have a mask, then TRUE is returned and FALSE otherwise.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_INVALIDCODE(3),
             AS_ERROR_UNSUPPORTED(10).
Notes:
             The width and height of the image may differ from the current
             sprite dimensions. After a call to as_Animate the board must be
             repainted. For efficiency reasons an invalid rectangle may be
             given, to mark the differences between the old and the new image.
             This is especially useful, when playing an animation in a sprite
             that uses differential encoding between sequential images.
             Differential encoding algorithms usually mark the image area that
             change from one image to the next.

             The image bits should refer to the same palette as the one the
             board is created with. Which in turn should be realized during
             painting (see as_PaintBoard).

See also:    as_Create,
             as_PaintBoard.





============================================================================
as_Assign

as_Assign assigns the sprite to a board layer, which gives a relative z-
order level. The lowest layer is zero and highest is INT_MAX. Initially
all levels are empty. Sprites may be reassigned within the same board and
assigments may be aborted.



Syntax:      BOOL as_Assign(ASBOARD Board, int Layer,
                            ASPRITE Sprite)

             Board       Identifies the board.

             Layer       The layer on the board the sprite must be assigned
                         to or -1 to abort a layer assignment.

             Sprite      Identifies the sprite.
Returns:
             If the sprite is detached from the layer, then TRUE is returned
             if it was indeed previously assigned to the board.

             Assignments are valid if the sprite was either not yet assigned
             at all or assigned to this board. In both cases TRUE is re-
             turned.
             FALSE is returned in case of illegal assigments.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_BOARDMISMATCH(2),
             AS_ERROR_INVALIDCODE(3),
             AS_ERROR_UNASSIGNED(9),
             AS_ERROR_UNSUPPORTED(10).

Notes:       AniSprite allows a number of sprites at the same layer. The real
             z-order processing for sprites at the same layer is indetermin-
             ate.

See also:    as_GetValue/ AS_VALUE_LAYER,
             as_GetBoardValuePtr/ AS_VALUEPTR_SPRITE.





============================================================================
as_Collide

as_Collide detects if the two sprites collide. A collision is defined as a
non-empty intersection of the opaque parts of the sprites.



Syntax:      BOOL as_Collide(ASPRITE Sprite1, ASPRITE Sprite2)

             Sprite1,
             Sprite2     Sprite identifiers.

Returns:     If the sprites collide then TRUE is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_UNASSIGNED(9).
Notes:
             as_Collide detects collisions regardless the current visibility
             state and layer of the sprites.

See also:    as_CollideBox,
             as_GetValue/AS_VALUE_LAYER,
             as_InBox.





============================================================================
as_CollideBox

as_CollideBox determines if the sprite and the box collide. A collision is
defined as a non-empty intersection of the opaque part of the sprite and the
box.



Syntax:      BOOL as_CollideBox(ASPRITE Sprite, LPRECT lpBox)

             Sprite      Identifies the sprite.

             lpBox       Gives box position and dimensions.

Returns:     If the sprite and box collide then TRUE is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_UNASSIGNED(9).

Notes:       as_CollideBox detects collisions regardless the current visibil-
             ity state and layer of the sprite.

See also:    as_Collide,
             as_GetValue/AS_VALUE_LAYER,
             as_InBox.

============================================================================
as_Create

as_Create creates a new sprite. Initially the sprite is invisible and its
position is (0, 0). Before a sprite can be moved, shown etc. it must be
assigned to a board.



Syntax:      BOOL as_Create(LPASPRITE lpSprite,
                            int Width, int Height,
                            LPVOID lpMask, int MaskCode,
                            LPVOID lpImage, BOOL ImageMasked)

             lpSprite    Address where to store the newly created sprite.

             Width,
             Height      Dimensions of the sprite. This must be the real mask
                         and image dimensions.

             lpMask      The mask bits in 8-bpp DIB format. When the sprite
                         does not have a mask, (see MaskCode) the lpMask
                         parameter is ignored. AniSprite supports three
                         different masks:

                           * cutout mask
                                Cutout masks have an optimized blit function
                                if the image bits have been masked out (see
                                ImageMasked parameter).

                           * brightness mask

                           * alpha mask

             MaskCode    The MaskCode indicates the type of mask that is
                         supplied. It can be any of the following values:
                           * AS_MASK_NONE(0)
                           * AS_MASK_CUTOUT(1)
                           * AS_MASK_SHINE(2)
                           * AS_MASK_ALPHA(3)

             lpImage     The image bits in 8-bpp DIB format.
            ImageMasked
                         This boolean variable indicates, whether the
                         transparent parts of the image have already been masked
                         out.

                         When the supplied mask is a cutout mask and the
                         image has been masked out, AniSprite can speed
                         up the off screen image blitting. In other cases,
                         masking out is useless.

Returns:     If there was enough memory to allocate the sprite resources then
             TRUE is returned is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_INVALIDCODE(3),
             AS_ERROR_OUTOFMEMORY(8).

Notes:       A sprite that is created with as_Create must be deleted with
             as_Delete.

             The image bits should refer to the same palette as the one the
             board is created with. Which in turn should be realized during
             painting (see as_PaintBoard).

See also:    as_Assign,
             as_Delete.





============================================================================
as_CreateAlphaLevel



Syntax:      LPVOID as_CreateAlphaLevel(LPRGBQUAD lpPal,
                                         double InterFactor)

             lpPal       Address of an array with 256 RGBQUAD's defining a
                         256 color palette. From this palette an alpha level
                         lookup table is calculated.

                         To retrieve an empty alpha level, lpPal must be set
                         to NULL. In that case the InterFactor is ignored.

             InterFactor
                         The InterFactor gives the relative distance for the
                         blended colour. InterFactor 0.0 means foreground colour
                         and 1.0 means background colour. Values in between mix
                         foreground and background proportionally.

Returns:     Returns a 32-bit pointer to a 64 kB memory block. This memory
             resource must be deleted with as_DeleteResource.

             In case of memory shortage NULL is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_OUTOFMEMORY(8).

Notes:       When an alpha level has been saved to disk, it can be loaded
             into a memory block that is allocated by as_CreateAlphaLevel
             with lpPal set to NULL. This is especially useful in 16-bit
             mode, because in that case the alpha level pointer must have a
             zero offset (see as_SetBoardValuePtr).

See also:    as_DeleteResource,
             as_GetBoardValuePtr,
             as_SetBoardValuePtr.





============================================================================
as_CreateBoard

as_CreateBoard creates an animation area which is called a board. Any
animation takes place on a board. The number of sprites that animate on a
board is unlimited, although animation speed will decrease with a too high
a number of sprites. A board is based on a background image and has colour
information for all bitmap objects related to the board. When not all of the
background image is involved in the animation, the board may be defined as a
part of that bitmap. This part is called the visible part of the bitmap.

If the board is configured to support alpha blending or back shining, it is
initialized with two levels. The preset alpha levels are fully opaque and
fully transparent for levels 0-127 and 128-255 respectively. The brightness
levels are initialized with black and normal brightness for levels 1-127 and
128-255 respectively (level zero is opaque in back shining masks).


Syntax:      BOOL as_CreateBoard(LPASBOARD lpBoard,
                                 LPBITMAPINFO lpBitsInfo,
                                 LPVOID lpBits,
                                 LPRECT lpVisRect, int Code)

             lpBoard     Address where to store the newly created board.

             lpBitsInfo  Pointer to a BITMAPINFO structure that describes the
                         DIB image bits.

             lpBits      Pointer to the image bits in 8-bpp DIB format.

             lpVisRect   Part of the image bits that is used as visible
                         board. If lpVisRect equals NULL, then the whole
                         bitmap is visible and the board dimension equal the
                         image dimensions.

             Code        Code describes the board capabilities. Those capab-
                         ilities are:

                           * AS_MODE_PAL_COLORS(0x01)
                                Use palette colors when blitting, i.e. An-
                                iSprite may assume that the palette in the
                                BITMAPINFO structure is always realized during
                                as_PaintBoard. For palette matters see for
                                instance EGI manual.

                           * AS_MODE_BACKSHINING(0x02)
                                Board supports and will be prepared for back
                                shining.

                           * AS_MODE_ALPHABLENDING(0x04)
                                Board supports and will be prepared for alpha
                                blending.

Returns:     If there was enough memory to allocate the board then TRUE is
             returned.
Errors:      AS_ERROR_NONE(0),AS_ERROR_OUTOFMEMORY(8).


Notes:       To reduce the memory needs for an animation the board must
             be defined as small as possible. Since AniSprite allocates a
             scratch area for the board, the memory needs are proportional to
             the size of the board. Use the lpVisRect parameter to optimize
             the size of the visible board area.





============================================================================
as_CreateBrightnessLevel



Syntax:      LPVOID as_CreateBrightnessLevel(LPRGBQUAD lpPal,
                                              double Brightness)

             lpPal       Address of an array with 256 RGBQUAD's defining a
                         256 color palette. From this palette a brightness
                         level lookup table is calculated.

                         To retrieve an empty brightness level, lpPal must be
                         set to NULL. In that case the Brightness is ignored.

             Brightness  Relative brightness value. Brightness value 0.0
                         means black and 1.0 is the identity brightness
                         value. The maximum useful brightness value is 256.0,
                         because colour components are scaled from 0 to 256.

Returns:     Returns a 32-bit pointer to a 256 bytes memory block. When no
             longer needed, delete this block with as_DeleteResource.

             In case of memory shortage NULL is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_OUTOFMEMORY(8).
Notes:
             The algorithm works the following. For each palette colour a new
             colour is calculated by multiplying all colour components (r,g,b)
             with the given brightness value. The palette index of the palette
             colour that is nearest to this new colour, is stored as lookup
             value.

             In other words the 256 byte lookup table is an array of palette
             indexes. For each palette colour its corresponding lookup index,
             is the palette colour that is nearest to the adjusted brightness
             colour.

See also:    as_DeleteResource,
             as_GetBoardValuePtr,
             as_SetBoardValuePtr.





============================================================================
as_CreateMask

as_CreateMask creates a mask for the given image. The values in the returned
DIB image bits range from 0 to 255. In general 0 means completely opaque
and 255 means completely transparent (see notes). Deriving a mask in this
way, requires the image positions that must be transparent to be in special
transparent colours. Consequently those colours cannot be used in the opaque
parts of the image.



Syntax:      LPVOID as_CreateMask(LPBITMAPINFO lpBitsInfo,
                                  LPVOID lpBits, BOOL MaskImage,
                                  COLORREF _FAR *crTransColor,
                                  int Colors)

             lpBitsInfo  Pointer to a BITMAPINFO structure that describes the
                         DIB image bits.

             lpBits      Pointer to the image bits in 8-bpp DIB format.
             MaskImage
                         Boolean to indicate whether the transparent parts in
                         the source image should be masked out. Sprites with
                         masked out images can be blitted faster to the off
                         screen buffer.


             crTransColor
                         Address of an array with the colors that are con-
                         sidered more or less transparent. The color order
                         in the array determines the amount of transparency
                         (see notes). Color i in the array has transparency
                         according to the next formula:


                                   (i+1)x255
                                      Colors

             Colors      Number of elements in the crTransColor array.

Returns:     Returns a 32-bit pointer to the mask bits memory block. This
             memory resource must be deleted with as_DeleteResource.

             In case of memory shortage NULL is returned. When the image is
             completely opaque, as_CreateMask returns NULL too.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_OPAQUE(7),
             AS_ERROR_OUTOFMEMORY(8).

Notes:       Masks created with as_CreateMask can be used as image mask
             for a sprite, either to create a new sprite with or animate
             an existing one. Depending on how the mask is interpreted the
             opaqueness and transparency may differ. Used as cutout mask,
             the bit value 0 always means opaque and 255 transparent, but
             if used as shine mask or alpha mask the meaning depends on the
             actual realized alpha levels / brightness levels in the board
             (see alpha blending and back shining).

See also:    as_Animate,
             as_Create,
             as_SmoothMask.

============================================================================
as_Delete



Syntax:      BOOL as_Delete(LPASPRITE lpSprite)

             lpSprite    Address where the sprite is stored.

Returns:     If the sprite is not assigned to a board layer then TRUE is
             returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_ASSIGNED(1).

Notes:       A sprite that is deleted may not be assigned to a board layer.
             If it is, it should be detached with as_Assign.

             as_Delete does not free the sprite image and mask.

See also:    as_Assign,
             as_Create.





============================================================================
as_DeleteBoard

This function deletes a board that was created with as_CreateBoard. All at-
tached resources like alpha levels and sprites should be deleted separately.
Before deleting a board all layers must be empty.



Syntax:      BOOL as_DeleteBoard(LPASBOARD lpBoard)

             lpBoard     Address where the board is stored.

Returns:     Returns TRUE if all layers were empty.
Errors:      AS_ERROR_NONE(0),AS_ERROR_NOTEMPTY(6),


Notes:       A board that is deleted may not have any sprites assigned to its
             layers. If it has, they should be detached first with as_Assign.

             as_DeleteBoard does not free the background image.

See also:    as_Assign,
             as_DeleteResource.





============================================================================
as_DeleteResource

as_DeleteResource deletes a resource that is created by AniSprite.



Syntax:      LPVOID as_DeleteResource(LPVOID Resource)

             Resource    Pointer to the resource that is created by

Returns:     Always returns NULL.

Errors:      AS_ERROR_NONE(0).

Notes:       The return value can be assigned to the resource pointer to
             invalidate it. Objects that have their own release function must
             be deleted by that function.

See also:    as_CreateMask,
             as_CreateAlphaLevel,
             as_CreateBrightnessLevel,
             as_Delete,
             as_DeleteBoard.

============================================================================
as_GetBoardValue



Syntax:      int as_GetBoardValue(ASBOARD Board, int Code,
                                  int Index)

             Board       Board identifies the board.

             Code        Code indicates which board value is to be retrieved.
                         The board code can be any of the following values:

                           * AS_VALUE_HEIGHT(10)
                                Returns the height of the animation board.

                           * AS_VALUE_MASKSUPPORT(14)
                                Returns TRUE if the given mask number is
                                supported by the board. The Index parameter
                                must be supplied with the mask number.

                           * AS_VALUE_NUMSPRITES(15)
                                Returns the number of sprites assigned to
                                the board layer. The Index parameter must be
                                supplied with the layer number. To retrieve
                                the total number of sprites assigned to the
                                board, Index must be set to -1.

                           * AS_VALUE_PALCOLORS(16)

                           * AS_VALUE_WIDTH(18)
                                Returns the width of the animation board.

                           * AS_VALUE_XPOS(19)
                                Returns the x-coordinate of the left side of
                                the animation board.

                           * AS_VALUE_YPOS(20)
                                Returns the y-coordinate of the top side of
                                the animation board.
             Index
                         Some board values can be indexed, in which case Index
                         is used. Otherwise Index is ignored.

Returns:

             Returns the appropriate value. All coordinates are relative to
             the upper left corner of the board image.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_INVALIDCODE(3),
             AS_ERROR_INVALIDINDEX(4).

Notes:

See also:    as_GetBoardValuePtr,
             as_SetBoardValue.





============================================================================
as_GetBoardValuePtr



Syntax:      LPVOID as_GetBoardValuePtr(ASBOARD Board,
                                         int Code, int Index)

             Board       Board identifies the board.

             Code        Code indicates which board value is to be retrieved.
                         The board code can be any of the following values:

                           * AS_VALUEPTR_ALPHA_LEVEL(0)

                           * AS_VALUEPTR_BOX(2)
                                Returns the visible area of the supplied
                                bitmap that represents the animation board.

                           * AS_VALUEPTR_BITMAPINFO(3)

                           * AS_VALUEPTR_IMAGEBITS(4)
                           * AS_VALUEPTR_SPRITE(6)
                           * AS_VALUEPTR_BRIGHTNESS_LEVEL (7)

             Index       Some board value can be indexed, in which case Index
                         is used. Otherwise Index is ignored.

Returns:     Returns the appropriate value pointer.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_INVALIDCODE(3),
             AS_ERROR_INVALIDINDEX(4).

Notes:

See also:    as_GetBoardValue,
             as_SetBoardValuePtr.





============================================================================
as_GetValue



Syntax:      int as_GetValue(ASPRITE Sprite, int Code)

             Sprite      Sprite identifies the sprite.

             Code
                           * AS_VALUE_HEIGHT(10)
                           * AS_VALUE_LAYER(11)
                           * AS_VALUE_MASKCODE(12)
                           * AS_VALUE_MASKED(13)
                           * AS_VALUE_VISIBLE(17)
                           * AS_VALUE_WIDTH(18)
                           * AS_VALUE_XPOS(19)
                           * AS_VALUE_YPOS(20)

Returns:     Returns the appropriate value. All coordinates are relative to
             the upper left corner of the board image.
Errors:      AS_ERROR_NONE(0),AS_ERROR_INVALIDCODE(3).


Notes:

See also:    as_GetValuePtr,
             as_SetValue.





============================================================================
as_GetValuePtr



Syntax:      LPVOID as_GetValuePtr(ASPRITE Sprite, int Code)

             Sprite      Sprite identifies the sprite.

             Code
                           * AS_VALUEPTR_BOARD(1)
                           * AS_VALUEPTR_BOX(2)
                           * AS_VALUEPTR_IMAGEBITS(4)
                           * AS_VALUEPTR_MASKBITS(5)

Returns:     Returns the appropriate value pointer.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_INVALIDCODE(3).

Notes:

See also:    as_GetValue,
             as_SetValuePtr.

============================================================================
as_InBox

as_InBox determines if the sprite is completely enclosed in the box. That
is, there are no opaque parts of the sprite outside the box.



BOOL as_InBox(ASPRITE Sprite, LPRECT lpBox)

Sprite       Identifies the sprite.

lpBox        Gives box position and dimensions.

Returns:     Returns TRUE if the opaque parts of the sprite are completely
             enclosed in the given box.

Errors:      AS_ERROR_NONE(0).

Notes:       as_InBox doesn't take the visibility state of the sprite into
             account.

See also:    as_Collide,
             as_CollideBox





============================================================================
as_LevelInMask



Syntax:      BOOL as_LevelInMask(int Width, int Height,
                                 LPVOID lpMask, int Level)

             Width,
             Height      Dimensions of the masks.

             lpMask      Pointer to the mask image bits in 8-bpp DIB format.
             Level       The alpha or brightness level to search for.
Returns:     Returns TRUE if the alpha or brightness level is present in the
             mask.

Errors:      AS_ERROR_NONE(0).

Notes:       The given level must be between 0 and 255. as_LevelInMask does
             not differentiate between masks. Applying the function to a
             cutout mask is therefore also possible, but not so very useful.

See also:    as_CreateMask,
             as_SetBoardValuePtr,
             as_SmoothMask,
             AS_VALUEPTR_ALPHA_LEVEL,
             AS_VALUEPTR_BRIGHTNESS_LEVEL.





============================================================================
as_MonoToColorMask



Syntax:      LPVOID as_MonoToColorMask(int Width, int Height,
                                        LPVOID lpMonoBits)

             Width,
             Height      Dimensions of the monochrome mask bits. This must be
                         the real mask dimensions.

             lpMonoBits

Returns:

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_OUTOFMEMORY(8).

Notes:

See also:    as_SmoothMask.

============================================================================
as_Move



Syntax:      BOOL as_Move(ASPRITE Sprite, int X, int Y)

             Sprite      Sprite identifies the sprite.

             X,
             Y           The new absolute sprite position. The sprite origin
                         is always the top left corner.

Returns:     If the sprite could be moved, .i.e. it was assigned to a board
             then TRUE is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_UNASSIGNED(9).

Notes:       After a call to as_Move the board must be painted if the sprite
             was visible. All coordinates are relative to the upper left
             corner of the board image.

See also:    as_PaintBoard.





============================================================================
as_PaintBoard

The function as_PaintBoard is used to update the screen, so that it repres-
ents the current state of the board.



Syntax:      BOOL as_PaintBoard(HDC hDC, ASBOARD Board,
                                int X, int Y, BOOL PaintAll)

             hDC
             Board       Identifies the board.
             X,
             Y           Origin for the board bitmap image. The board area is
                         painted relative to this position.

             PaintAll    Indicates whether the whole board must be updated
                         or just the parts that were invalidated after
                         the previous call to as_PaintBoard. Typically
                         PaintAll is TRUE, when as_PaintBoard is called in
                         the WM_PAINT message processing. When called after
                         some sprite movements or sprite animations have been
                         executed, PaintAll should be FALSE.

Returns:     Returns TRUE if there was any blitting to the hDC.

Errors:      AS_ERROR_NONE(0).

Notes:       After as_PaintBoard has been called, there are no invalid parts
             left. This does not imply that the situation on the screen
             represents the real animation board situation. Errors occur when
             you incorrectly set PaintAll to FALSE.

See also:    as_Animate,
             as_Move,
             as_ReplaceBoard.





============================================================================
as_PtInBoard



Syntax:      BOOL as_PtInBoard(ASBOARD Board, int X, int Y)

             Board       Identifies the sprite.

             X,
             Y           The position that may be in the board.
Returns:
Errors:      AS_ERROR_NONE(0).

Notes:

See also:    as_PtInSprite,
             as_CollideBox.





============================================================================
as_PtInSprite

as_PtInSprite tests if a given position lies in the opaque parts of the
sprite. If the sprite has no mask it is obviously completely opaque.



Syntax:      BOOL as_PtInSprite(ASPRITE Sprite, int X, int Y)

             Sprite      Identifies the sprite.

             X,
             Y           The position that may be in the opaque parts of the
                         sprite.

Returns:     Returns TRUE if the point is indeed in the opaque parts of the
             sprite.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_UNASSIGNED(9).

Notes:       as_PtInSprite considers 0 as opaque regardless of the type of
             mask and realized alpha levels / brightness levels in the board.
             as_PtInSprite does not look after the current visibility state
             and layer of the sprite. Possible sprites on top of the sprite
             are ignored.

             Coordinates are relative to the upper left corner of the board
             image.
See also:    as_SpriteAtPos.





============================================================================
as_ReplaceBoard

This function can be used to change the board background image and/or
visible area within the bitmap. Whether either of the two remains the
same or not, both the bitmap and visible area must be supplied as valid
parameters.



Syntax:      BOOL as_ReplaceBoard(ASBOARD Board,
                                  int Width, int Height,
                                  LPVOID lpBits, LPRECT lpVisRect,
                                  LPRECT lpInvalidRect)

             Board       Identifies the board.

             Width,
             Height      Dimensions of the board. This must be the real image
                         dimensions.

             lpBits      The new board image bits.

             lpVisRect   Visible part of the new board image.

             lpInvalidRect
                         Part of board image that changes as a consequence of
                         the animation. When all of the image changes or if
                         you don't care or don't know, set lpInvalidRect to
                         NULL.

Returns:     If there was enough memory to allocate the new board resources,
             then TRUE is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_OUTOFMEMORY(8).
Notes:
             To update the board change to the screen the board must be painted
             with as_PaintBoard.

See also:    as_CreateBoard,
             as_DeleteBoard,
             as_PaintBoard.





============================================================================
as_SetBoardValuePtr

This function sets an alpha level or brightness level. To be able to set a
certain level for a board, the board must be configured accordingly.



Syntax:      BOOL as_SetBoardValuePtr(ASBOARD Board,
                                       int Code, int Index,
                                       LPVOID Value)

             Board       Identifies the board.

             Code        Code indicates which board value is to be modified.
                         The board code can be any of the following values:

                           * AS_VALUEPTR_ALPHA_LEVEL(0)
                                Typically alpha levels are installed, so
                                that they enable alpha masks to gradually
                                mix foreground and background pixel colours.
                                However it is up to the programmer to choose
                                the levels as (s)he pleases.

                                An alpha level points to a memory block of
                                exactly 64 kB. In 16-bit mode the value
                                pointer must have zero offset.

                           * AS_VALUEPTR_BRIGHTNESS_LEVEL(7)

             Index       Index indicates which alpha or brightness level is
                         to be modified.
             Value       The data pointer that must be set.
Returns:     Returns TRUE if the parameters were valid.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_INVALIDCODE(3),
             AS_ERROR_INVALIDINDEX(4),
             AS_ERROR_INVALIDPOINTER(5) (16-bit only).

Notes:

See also:    as_CreateAlphaLevel,
             as_CreateBoard,
             as_CreateBrightnessLevel,
             as_GetBoardValuePtr,
             AS_MODE_ALPHABLENDING,
             AS_MODE_BACKSHINING,
             as_SetBoardValue.





============================================================================
as_Show

as_Show



Syntax:      BOOL as_Show(ASPRITE Sprite, BOOL Show)

             Sprite      Identifies the sprite.

             Show        Boolean to indicate whether the sprite is to be
                         shown or hidden.

Returns:     If the visibility state of the sprite changed then TRUE is
             returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_UNASSIGNED(9).
Notes:
             Visibility changes must be updated with as_PaintBoard; as_Show
             itself doesn't change the screen contents.

See also:    as_PaintBoard,
             as_GetValue/AS_VALUE_VISIBLE.





============================================================================
as_SmoothMask

as_SmoothMask returns a smoothed version of the given (cutout) mask. Only
the opaque parts of the mask are smoothed. This function is useful for
making alpha masks from cutout masks



Syntax:      LPVOID as_SmoothMask(int Width, int Height,
                                  LPVOID lpMask, int Order)

             Width,
             Height      Dimensions of the masks.

             lpMask      The mask bits in 8-bpp DIB format.

             Order       Smoothing order.2The mask is smoothed using a

                         (2 x Order + 1)  matrix of the following form:



                                   z2xOrder+1"_-

                                     0. ... . 1. ... . 0.

                                     .   .    .   .    .

                       1( .   .    .   .    .)
                       4 x Order + 1 1. ... . 1. ... . 1.
                                     .   .    .   .    .
                                     .   .    .   .    .
                                     0  . . . 1  . . . 0
Returns:
             A 32-bit pointer to the new mask is returned. This memory block
             must be freed by as_DeleteResource.
             If there was not enough memory available, then NULL is returned.

Errors:      AS_ERROR_NONE(0),
             AS_ERROR_OUTOFMEMORY(8).

Notes:       This function is useful for making alpha masks from cutout
             masks.

See also:    as_CreateMask.





============================================================================
as_SpriteAtPos



Syntax:      ASPRITE as_SpriteAtPos(ASBOARD Board, int X, int Y)

             Board       Identifies the board.

             X,
             Y           The position that may be in the opaque parts of any
                         sprite that is assigned to the board.

Returns:     The top most visible sprite that is opaque at the given pos-
             ition. If no sprite is found at this position, then NULL is
             returned.

Errors:      AS_ERROR_NONE(0).

Notes:       In contrast to as_PtInSprite this function takes the z-order
             level of the sprites into account.

See also:    as_PtInSprite.
                                   Error codes

****************************************************************************
----------------------------------------------------------------------------

AS_ERROR_NONE(0)
           No error.

AS_ERROR_ASSIGNED(1)
           Trying to delete a sprite that is still assigned to a board layer.
           When a sprite is deleted, it may not be part of an animation to
           prevent from inconsistent board situations afterwards.

AS_ERROR_BOARDMISMATCH(2)
           Occurs when a sprite is reassigned to a board layer, while it's
           already assigned to a layer of another board. Reassigments are
           only allowed within the same board.

           Although AniSprite is perfectly capable of handling crossboard
           reassignments, we forbid them because it is a very unlikely an
           action.

AS_ERROR_INVALIDCODE(3)
           Any of the value (pointer) setting / retrieval functions, was
           called with an invalid code. See the valid codes in the function
           documentation.

AS_ERROR_INVALIDINDEX(4)
           Any of the value (pointer) setting / retrieval functions, was
           called with an invalid code index. See the valid codes in the
           function documentation.

AS_ERROR_INVALIDPOINTER(5)
           This error can only occur in 16-bit mode. It is a rather technical
           story. Since we use far pointers to access alpha level data and
           one alpha level block is exactly 64 kB, the pointer offset of an
           alpha level must be zero. If it's not this error occurs.

AS_ERROR_NOTEMPTY(6)
           This error is the counterpart of AS_ERROR_ASSIGNED. When deleting
           a board all board layers must be empty or in other words: there
           may be no sprites left assigned to the board. See the How to?
           chapter / section Clean up an animation.
AS_ERROR_OPAQUE(7)AniSprite can make a mask from an image using transparent
            colours.

           If none of the given transparent palette colors is in the image
           palette, AniSprite generates this error.

AS_ERROR_OUTOFMEMORY(8)
           When AniSprite encounters memory shortage while creating objects
           or allocating temporary memory resources, it sets the out of
           memory error and leaves all as it was before the function was
           called.

AS_ERROR_UNASSIGNED(9)
           Most sprite operations can only take place if the sprite is
           assigned to a board layer. If it's not AniSprite generates an
           unassigned error.

AS_ERROR_UNSUPPORTED(10)
           If the mask capabilities of a board are limited this error may
           occur during as_Assign or as_Animate. Enabling mask types for a
           board must be done when the board is created.
