                                  AniSprite

****************************************************************************
----------------------------------------------------------------------------
                                                                 Version 2.1



----------------------------------------------------------------------------
****************************************************************************
                                                              ITB CompuPhase
iv                                                            ITB CompuPhase

"Borland" and "Borland C++" are registered trademarks, and "Delphi" is
    a trademark of Inprise International, Inc.
"IBM" and "OS/2" are registered trademarks of International Business
    Machines Corporation.
"Microsoft" and "Microsoft Windows" are registered trademarks, and
    "Visual Basic" and "Visual C/C++" are trademarks of Microsoft
    Corporation.
"Paint Shop Pro" is a trademark of JASC, Inc.
"Pro Motion" is a product of Cosmigo.
"Watcom" is a trademark of Sybase, Inc.
"CompuPhase" and "EGI" are registered trademarks of ITB CompuPhase, and
    "AniSprite" and "Panodome" are trademarks of ITB CompuPhase.



Copyright (c) 1996--1999, ITB CompuPhase, Brinklaan 74-b, 1404 GL Bussum,
Netherlands (Pays Bas); tel.: +31 35 693 9261; fax: +31 35 693 9293;
CompuServe: 100115,2074; e-mail: info@compuphase.com;
WWW: http://www.compuphase.com

No part of this manual may be reproduced or transmitted by any means (elec-
tronic, photocopying or otherwise), without prior written permission by ITB
CompuPhase.

The examples and programs in this manual have been included for their
instructional value. They have been tested with care, but are not guaranteed
for any particular purpose.
AniSprite                                                                  v

                              Table of Contents

****************************************************************************
----------------------------------------------------------------------------
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
    Animation  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Using AniSprite  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
    General operation  . . . . . . . . . . . . . . . . . . . . . . . . . . 8
    Masks  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
    Compiling and linking  . . . . . . . . . . . . . . . . . . . . . . .  11
    Memory management  . . . . . . . . . . . . . . . . . . . . . . . . .  13
    Set up an animation  . . . . . . . . . . . . . . . . . . . . . . . .  13
    Clean up an animation  . . . . . . . . . . . . . . . . . . . . . . .  14
    Fade an image  . . . . . . . . . . . . . . . . . . . . . . . . . . .  15
    Callback functions . . . . . . . . . . . . . . . . . . . . . . . . .  18
    Tips for optimizing AniSprite  . . . . . . . . . . . . . . . . . . .  22
    A programming example  . . . . . . . . . . . . . . . . . . . . . . .  23
Function reference . . . . . . . . . . . . . . . . . . . . . . . . . . .  28
Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  84
    A: Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . .  85
    B: Using AniSprite with EGI  . . . . . . . . . . . . . . . . . . . .  88
    C: Using the "trace" DLLs  . . . . . . . . . . . . . . . . . . . . .  91
    D: Getting more information  . . . . . . . . . . . . . . . . . . . .  92
Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  93
vi                                                            ITB CompuPhase



AniSprite                                               Introduction  ---  1

                                Introduction

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

AniSprite is a multiple layer sprite animation library for Microsoft Windows
3.1, Windows 95 and Windows NT. It is aimed at games and multi-media pro-
grammers. AniSprite can be used with any language or environment that can
call a DLL; interfaces for C/C++ and Visual Basic are provided.


Features

AniSprite has all the standard features that one expects in a sprite li-
brary, such as flicker free/multi-layer animations. In addition, AniSprite
supports:



* alpha blending between sprites and the background image, which enables
  anti-aliased edges, translucent sprites and sprite fading
* shadows and flare effects, in any colour
* multiple animation areas
* 256 colour pictures, any palette
* unlimited number of sprites
* transparent boards, move sprites over the Windows desktop
* screen grab, system palette grab
* callbacks ("events") for custom painting or ---automatic--- collision
  detection
* high performance, optimized "dirty rectangle" calculation with minimum
  overwrite, critical routines in optimized assembler
* supports DIB sections on Windows 95 and Windows NT
* uses the "mmsystem" timer (higher resolution and more reliable than the
  standard Windows timer), but without the "mmsystem" callback function
  restrictions
* 16 bit and 32 bit implementation
* each sprite has an origin (which may lie outside the sprite)
* sprites can be linked, moving the master also moves the linked ones
* many "utility" functions to crop sprites to the smallest bounding box,
  to create, convert or modify masks, to adjust images images to a specific
  palette, etc.
* Windows DLL interface, libraries/definition files for C/C++ and Visual
  Basic
2  ---  Animation                                             ITB CompuPhase

* flexible design, integrates with EGI (frame animation engine, see appendix
  B) and other graphic libraries
* dynamic sprites (support for callback functions per sprite)
* an assortment of utility functions to map DIBs to different palettes,
  to resize a DIB or its mask, to create a mask from a colour key (chroma
  keying), etc.
* both low-level and medium-level interfaces, direct access to the bitmap
  data of sprites, masks and the animation frame
* separate "trace" DLLs verify more function parameters than the standard
  DLLs and send this information to the (kernel) debugger, at the cost of
  executing slower than the standard DLLs. The trace DLLs are included in
  the retail version only. See appendix C for more information.
* full source is available



Animation

Animation has many faces, as it covers any change of appearance or any
visual effect that is time-based. It includes motion (change of position),
time-varying changes in shape, colour (palette), transparency and even
changes of the rendering technique.

Two typical computer animation methods are "frame" animation and sprite
animation. Frame animation is animation inside a rectangular frame. It is
similar to cartoon movies: a sequence of frames that follow each other at a
fast rate, fast enough to convey fluent motion.

Frame animation is an "internal" animation method. It is typically pre-
compiled and non-interactive. The frame is typically rectangular and non-
transparent. Frame animation with transparency information is also referred
to as "cel" animation. In traditional animation, a cel is a sheet of
transparent acetate on which a single object (or character) is drawn.

Sprite animation, in its simplest form, is a two-dimensional graphic object
that moves across the display. Sprites often can have transparent areas.
By using a mask or a transparent colour, sprites are not restricted to
rectangular shapes.

Sprite animation lends itself well to be interactive: the position of each
sprite is controlled by the user or by an application program (or by both).
It is called "external" animation. The famous "space invaders" game is a
typical, and old, example of sprite animation.
AniSprite                                                  Animation  ---  3

That said, nearly all sprite animation libraries and toolkits allow some
form of internal animation. That is, in addition to moving a sprite around,
the library allows you to change the appearance of the sprite, usually by
attaching a new image to the sprite.

Referring to the CompuPhase products: AniSprite is a sprite animation
library with (the common) support for multiple images per sprite, and EGI
is a frame animation engine/compiler, with some extensions towards sprite
animation. We think that by combining both products, you can achieve very
mobile sprites, or synchronized cartoon-like animations.
4  ---  Glossary                                              ITB CompuPhase

                                  Glossary

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

Action              A sprite action is one of the following:
                    * movement
                    * appearance change, that is a new mask or image
                    * 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 mean of the two
                    input images.

BitBlt              Bit Block Transfer: the copying of a rectangular memory
                    block (usually an image) to the display or to another
                    memory block.

Blitting            Doing a BitBlt.

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

Board window        AniSprite can paint the board in any valid display
                    context (HDC), but in some cases it is more convenient
                    to create a "board window" for the board. The board
                    window can automatically handle the palette for the
                    board and refresh the screen at regular intervals.

bpp                 Bits Per Pixel. The number of bits per pixel determines
                    the number of colours or grey levels that the pixel can
                    have. AniSprite uses 8-bpp images, which have a maximum
                    of 256 colours.

Chroma key          Chroma keying is a technique where one or more colours
                    in an image are considered more or less transparent. In
                    computer animation, it typically means that you specify
                    a single transparent colour with each image. A popular
                    colour that is used for transparency is magenta; RGB
                    values (255,0,255).
AniSprite                                                   Glossary  ---  5

Collision           Two sprites collide when their opaque parts "touch",
                    regardless of the layers that both sprites are in. In
                    other words, one sprite is obscured more or less by the
                    other sprite.

                    A sprite can also collide with a rectangle or another
                    (non-sprite) object.

Cutout mask         A binary opaque/transparent mask (see chapter "Masks"
                    on page  9).

DDB format          Device Dependent Bitmap format. Used internally by Mi-
                    crosoft Windows. The format is display driver dependent.

DIB format          Device Independent Bitmap format. Microsoft Windows uses
                    two image formats internally: DIBs and DDBs. The device
                    independent format is the preferred format, because it
                    contains colour information and because it is portable
                    across video drivers.

Identity palette    A palette that complies with a few restrictions. DIB
                    operations are significantly faster if an identity
                    palette is realized. See appendix D.

In-memory blitting  A BitBlt from one image in memory to another image in
                    memory. Neither of these images is on the display. A
                    standard BitBlt copies a memory image to the video
                    memory, thereby displaying it. In Microsoft Windows,
                    an in-memory BitBlt can be an order of magnitude faster
                    than a standard BitBlt. Therefore, AniSprite makes
                    extensive use of in-memory blitting.

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.
6  ---  Glossary                                              ITB CompuPhase

Linked sprites      A sprite may have linked sprites. Whenever the sprite
                    moves, all linked sprites move with the same horizontal
                    and vertical displacements. The "father" of the linked
                    sprites is called the master sprite.

Luma blending       Luma blending is a kind of Alpha blending. The destina-
                    tion pixel either equals the foreground pixel, or the
                    background pixel with adjusted brightness. You typically
                    use it to add shadow or spotlight reflections.

Master sprite       See "linked sprites".

Opaque              The opposite of transparent. Where the mask is "opaque"
                    you see the sprite.

Opaque level        When checking collisions between sprites, or between a
                    sprite and a rectangle, the opaque level determines at
                    what mask value a pixel in the sprite is "opaque".
                    When you add shadows to a sprite, you will usually
                    want to consider the shadow transparent. When you make
                    translucent ghosts, you will usually want to consider
                    them opaque (for collision detection). In other words,
                    the opaque level depends on the sprite.

Origin              Every sprite has an origin; the default origin is
                    the upper left corner of the sprite. When setting the
                    position of a sprite, you specify the coordinates the
                    origin of the sprite.

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.
                    An in-depth discussion of the Microsoft Windows Palette
                    Manager is available electronically, see appendix D.

Slot                The period in which sprite actions and board replace-
                    ments 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.
AniSprite                                                   Glossary  ---  7

Translucent         Somewhat transparent, somewhat opaque. You see the
                    background with an altered luminance (luma masks) or
                    a weighted mixture of the sprite and background pixels
                    (alpha masks).

Transparent         Where the mask of a sprite is transparent, you see
                    through the sprite. In other words, you see what is
                    below the sprite.
8  ---  Using AniSprite                                       ITB CompuPhase

                               Using AniSprite

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



General operation

Sprite animation is restricted to a rectangular area on the screen. This
area is called the "board". The board contains the background image and
a colour table (palette). The background image (or "board image") may be
larger than the board itself. In other words, the board is any cutout of the
board image.

The coordinates that you pass to an AniSprite function are relative to the
upper left corner of the board image. This applies both to functions that
deal with sprite coordinates (e.g. as_SetPos) as well as to board related
functions (like as_PaintBoard).

On a high level, AniSprite works by first painting the board image on the
computer display and then, one by one, painting all sprites on top of it.
Possibly, one sprite is painted on top of another sprite.

To avoid flicker, you should not draw directly to the display: drawing a
sprite at a lower level may damage a sprite at a higher layer. Instead,
AniSprite creates a scratch area with a size equal to that of the board. The
board and all sprites are first painted in the scratch area, and then the
scratch area is blitted at one blow to the computer display.

Actions of a sprite are therefore buffered. If, for example, you call
as_SetPos to give a sprite a new position, the sprite stay on the computer
display at its old location, until you call as_PaintBoard. The function
as_PaintBoard generates a new scratch area and displays the results.

AniSprite handles a few optimizations in the background. For example, it
rebuilds only those parts of the scratch area that actually change. The
point to stress here is that your program should call as_PaintBoard at
regular intervals, for example by installing a timer that generates a
WM_TIMER event every 50 milliseconds.

On the other hand, it is bad practice to call as_PaintBoard after every
single call to as_SetPos, as_Move, as_Animate or as_Show. The "buffered"
functions, like as_Move, are very fast, whereas the workhorse function
AniSprite                                                      Masks  ---  9

           [Sorry, this picture is missing from the ASCII version]

Figure 1: The sprite painting pipeline
----------------------------------------------------------------------------



           [Sorry, this picture is missing from the ASCII version]

Figure 2: Mask values in a Cutout mask
----------------------------------------------------------------------------



as_PaintBoard is slow in comparison. For optimal performance, you should
avoid that as_PaintBoard does double work, as when rebuilding (nearly) the
same scratch image when one sprite overlaps another sprite. The preferred
approach is that you call as_PaintBoard on a timer (and that you call it
only once at every timer tick). In the time between two ticks, you can move
and change all sprites at will. AniSprite calls the time between two timer
ticks a "slot".



Masks

When displaying a somewhat transparent foreground (sprite) 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 it
tells for each pixel at the destination location how to mix the sprite and
background colours. AniSprite supports three mask types: cutout masks, luma
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.

In AniSprite, the mask colour value 0 indicates an opaque pixel and 255
indicates a transparent pixel.
10  ---  Masks                                                ITB CompuPhase

           [Sorry, this picture is missing from the ASCII version]

Figure 3: Mask values in a Luma mask
----------------------------------------------------------------------------



           [Sorry, this picture is missing from the ASCII version]

Figure 4: Mask values in an Alpha mask
----------------------------------------------------------------------------



Luma mask

A "luma" mask is a multilevel mask that darkens or lightens objects below
them. A pixel in the sprite 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 light reflection (flare)
effects, for example, to suggest of perspective and depth.

In AniSprite, the mask colour value 0 means opaque and 255 means transpar-
ent. Values between 0 and 255 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 a multilevel mask that contains weighting values to average
two images. Any destination pixel colour is a mixture of sprite image and
the background image. A 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.

Typically, mask colour value 0 means completely opaque, 255 means completely
transparent and values in between gradually mix sprite and background
pixels. However, it is up to the user to install intermediate alpha level
tables for optimal alpha blending.
AniSprite                                     Compiling and linking  ---  11

Note that AniSprite works on 256 colour images with a palette. The colour of
the sprite and the background pixels come from this palette and the colour
of the weighted mix of the two pixels must be looked up in the palette as
well. AniSprite uses pre-calculated lookup tables to do this efficiently.



Compiling and linking

Each source file that calls the AniSprite functions should include ANIS-
PRI.H. This file is universal for 16-bit and 32-bit programs and (it is
hoped) for all C compiler brands.

Linking is less straightforward, due to incompatibilities between the tools
of compiler vendors. 16-Bit programs should link with AS16.LIB, regardless
of the compiler brand. Some compiler vendors may provide a utility (like
"IMPLIB") that creates a .LIB file for their linker from a DLL. For 32-bit
programs, there is a library file per supported compiler brand:
* AS32M.LIB for Microsoft Visual C/C++ version 4.0 or higher, and for other
  compilers that are compatible with the COFF object library format.
* AS32B.LIB for Borland C++ 4.5 or higher.
* AS32W.LIB for Watcom C/C++ 10.6 or higher.


Visual Basic

The AniSprite DLLs contain a type library that contains the function defini-
tions and constants of the AniSprite API. Accessing the AniSprite functions
merely involves that you add the AniSprite DLL (either the 16-bit or the
32-bit DLL) to the "references" of a project. After that, the AniSprite
function and constant definitions are available from the object browser.
* In Visual Basic 4.0, select "Tools" from the main menu bar and then
  click on "References...". In the dialog box, click on the "Browse..."
  button and open the relevant AniSprite DLL (AS16.DLL for 16-bit projects
  and AS32.DLL for 32-bit projects).
12  ---  Compiling and linking                                ITB CompuPhase

* In Visual Basic 6.0, select "Project" from the main menu bar and click
  on "References...". In the dialog box, click on the "Browse..." button
  and open the AS32.DLLfile.

The "Object browser" window is available from the "View" submenu, or
with function key F2.

You will find an AniSprite sample in Visual Basic in the "EXAMPLES"
subdirectory below the main AniSprite installation directory.

In the AniSprite philosophy, sprites are on a board and a board (or several
boards) are in a window. It is the responsibility of the window to deal
with palette realization and with the periodic refresh of the window (and
the board that it contains). For the purpose of high level languages, like
Visual Basic, AniSprite provides the function as_CreateBoardWindow. This
function creates a window that is palette aware and that automatically
intercepts (and handles) requests to refresh its contents.
AniSprite                                       Set up an animation  ---  13

Memory management

AniSprite needs to allocate memory for many of its operations. All memory
allocations done by AniSprite functions pass through as_AllocResource. When
an AniSprite releases a memory block, it does so by calling as_FreeResource.

An application that uses AniSprite functions may use its own memory alloca-
tor (malloc in C, or new in C++) and pass pointers to the allocated blocks
to AniSprite. Later, when the memory blocks are no longer needed, they can
be freed with the relevant "free" function.

And never the twain shall meet... Using as_FreeResource to release a memory
block that was allocated with malloc (or a similar mix-up) is a serious
error that may actually go undetected for a while.



Set up an animation

1. load the board image
   Load the bitmap in DIB format including the BITMAPINFO header and the
   palette. It is usually convenient to use as_AllocResource to allocate the
   memory for the DIB data, but you may use a different memory allocator.

2. create a board
   Given the bitmap and BITMAPINFO you can create a board. The visible board
   can be reduced to a part of the bitmap. At this moment the board installs
   its masking capabilities, which can not be extended afterwards.

3. create a palette
   Use the BITMAPINFO palette entries to set the palette for the board with
   as_SetPalette.

4. load luminance or alpha tables
   When the board is created to support alpha blending and/or luma blending,
   you may now create (or load) and install alpha levels and luma levels.

5. load sprite bitmaps
   Load each sprite bitmap in DIB format including the BITMAPINFO header.
   The bitmap palette should be the same as the board bitmap palette,
   otherwise you should first remap the bitmap so that it fits the board
   palette with as_ConvertImage.

   Again, it is usually convenient to use as_AllocResource to allocate the
   memory for the DIB data.
14  ---  Clean up an animation                                ITB CompuPhase

6. load or create sprite masks
   Load the mask image from disk or create it from the sprite image using
   transparent colours. In the latter case as_CreateMask does the job.

7. create sprites
   Use as_Create to create the sprite.

8. assign sprites to board layers
   Before sprites can come into action, they must be assigned to a board
   layer. Use as_Assign for this purpose.

9. 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 Microsoft
   Windows documentation).

   If you used as_SetPalette (see step 3), you can simply call the function
   as_ForwardMessage.

10.process the paint event message
   To actually display the board, the application must process the WM_PAINT
   message. When the application receives a WM_PAINT message, Microsoft
   Windows has built a clip list. AniSprite is unaware of the clip list,
   so you must instruct it to redraw the complete board (not only its
   invalidated areas).

   The code segment below assumes that you let AniSprite handle the palette
   hassle (see step 3).

   -------------------------------------------------------------------------
       case WM_PAINT:
           hDC = BeginPaint(hWnd, &ps);
           as_PaintBoard(hDC, Board, 0, 0, TRUE); /* PaintAll == TRUE */
           EndPaint(hWnd, &ps);
           break;
   -------------------------------------------------------------------------
   Figure 5: Processing the WM_PAINT event message



Clean up an animation
AniSprite                                             Fade an image  ---  15

1. cancel sprite assignments
   Cancel the board layer assignment with as_Assign(Sprite, Board, -1) for
   every sprite.

2. delete sprites, free images and masks
   If sprites are no longer assigned to a board, they can be deleted with a
   call to as_Delete. Function as_Delete can optionally also delete the DIBs
   for the images and masks.

3. free possible alpha levels and/or luma levels
   Using as_FreeResource or a custom memory manager.

4. delete the board and its image
   The board is deleted by a call to as_DeleteBoard. At this time there
   should no sprites left assigned to the board. Function as_DeleteBoard can
   optionally delete the board image.



Fade an image

With AniSprite's alpha blending feature, sprites can be faded in and out.
There are two ways to do this:
1. The mask can be adjusted repeatedly after installing a number of alpha
   levels in the board.
2. Repeatedly installing new alpha levels in the board. This option effects
   all sprites in the board that use alpha masks, but it is often faster.


1. Fading by adjusting the sprite mask

1. 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 two trivial alpha
   levels: transparent and opaque. Because we want a number of grades, we
   must install a number of alpha levels in the board.
16  ---  Fade an image                                        ITB CompuPhase

   A pixel in the mask has a value in the range 0--255. Although we can
   compute and setup up 256 lookup tables for alpha blending, the memory
   requirements are steep. What one usually does is to create a limited
   number of additional tables, say 15, and to map any of the 256 possible
   values of the mask to the nearest alpha lookup table.

   This is summarized in the following code snippet.

   -------------------------------------------------------------------------
           #define LEVELS  15

           for (i = 1; i <= LEVELS; i++) {
               Level = as_CreateAlphaLevel(Palette, i * 256 / (LEVELS + 1));
               as_SetBoardData(Board, AS_DATA_ALPHA_LEVEL, i, Level);
           } /* endfor */
   -------------------------------------------------------------------------
   Figure 6: Installing alpha levels for fading

   Note that two levels are already predefined. By creating 15 alpha tables,
   we get a total of 17 tables, in the range 0--15 and 255.

   The gap between full transparent (at level 255) and nearly transparent
   (at mask value 15) is inconvenient. So the next step is to set level
   16 to "full transparent" as well. One way to do this is to create an
   additional alpha level. Another way is to simply refer to the predefined
   table.

   -------------------------------------------------------------------------
           Level = as_GetBoardData(Board, AS_DATA_ALPHA_LEVEL, 255);
           as_SetBoardData(Board, AS_DATA_ALPHA_LEVEL, 16, Level);
   -------------------------------------------------------------------------
   Figure 7: Installing alpha levels for fading

2. retrieve the sprite mask
   From an existing sprite, the mask can be retrieved with as_GetData and
   parameter AS_DATA_MASKBITS. You can also store the mask pointer when
   creating the sprite.
AniSprite                                             Fade an image  ---  17

3. adjust the mask
   Increase or decrease the mask values. Assuming that the original mask
   is a cutout mask, you fade out by mapping mask value 0 (opaque) to mask
   value 1 (the first alpha level). At the next iteration, you would map
   mask level 1 to level 2, and so forth.

   Use as_MapMultiLevels to adjust the masks of sprites.

4. animate the sprite with the new mask
   Call as_Animate with the new mask (other parameters remain unchanged).

5. update the board
   Use as_PaintBoard to repaint the board.

6. repeat until the sprite is completely transparent or opaque
   That is, go back to step 2.


2. Fading by re-installing alpha levels

1. 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.

   Because alpha level calculation is time consuming we calculate a number
   of alpha levels beforehand and store them in an array. We do not install
   the levels in the board.

   Sprites that will be faded have binary masks with level 255 at transpar-
   ent parts and 0 at opaque parts.

2. modify alpha level
   Use the function as_SetBoardData to install a new alpha level from the
   previously calculated array at level 0 in the board.

3. invalidate sprites
   Invalidate all sprites that use an alpha mask.

4. update the board
   Use as_PaintBoard to update the new board situation.

5. repeat until last level installed
   That is, go back to step 2.
18  ---  Callback functions                                   ITB CompuPhase

Callback functions

Sprites are not always static objects. Sometimes you want to put context
sensitive text on top of the bitmap. To enable the user to adjust sprites
at run-time, AniSprite supports callback functions. as_PaintBoard calls
the callback function for any sprite that has installed one. The callback
function may modify the sprite appearance.

In fact, AniSprite supports multiple callback functions per sprite. The
callback events that are currently defined are:
* AS_EVENT_COLLIDE: the opaque part(s) of the sprite touches another sprite
  at the same layer. This callback is called from as_ForwardMessage.
* AS_EVENT_PAINT_DDB: the sprite is updated (repainted) using a device
  dependent bitmap (DDB). This callback is called from as_PaintBoard.
* AS_EVENT_PAINT_DIB: the sprite is updated using a device independent
  bitmap (DIB). This callback is called from as_PaintBoard.
* AS_EVENT_TIMER: a general purpose time tick event, at which the sprite may
  move or change appearance. This callback is called from as_ForwardMessage.
* AS_EVENT_MOUSE: for mouse events (click, move, leave) that occur on top of
  a sprite. This callback is called from as_ForwardMessage.


Callback function syntax

Syntax:  DWORD asCallBack(ASPRITE Sprite, int Event, DWORD Value, LPVOID
                          Data)

         Sprite      The sprite handle.

         Event       The event that occurred; any of the following:
                     * AS_EVENT_COLLIDE
                     * AS_EVENT_PAINT_DIB
                     * AS_EVENT_PAINT_DDB
                     * AS_EVENT_TIMER
                     * AS_EVENT_MOUSE

         Value       Extra event information, depends on the event.

         Data        Extra event information, depends on the event.
AniSprite                                        Callback functions  ---  19

Returns: Depends on the event.

The name asCallBack is a placeholder for a function name in your program.

A callback must be installed (using as_SetData). You may assign a single
callback function to multiple sprites, or you may write a separate function
for any sprite. Similarly, you may write a separate function for any event,
or handle all events with a single callback function.


DDB Callback functions

Callback functions using a DDB can use the Windows graphic functions to draw
into the sprite. AniSprite uses DIBs internally, so it needs to convert a
DIB to a DDB before the call. Afterwards the DDB must be converted back to
8-bpp DIB format.

When the application is running in a Windows environment with more than
256 colours, the conversion from the DDB to 8-bpp DIB is not perfect.
First there is inevitably colour depth reduction. Colour depth reduction is
usually done by palette matching using nearest colours. It is undesirable
to do this at run-time, because it is slow. To work around this problem,
AniSprite only converts the colours that are in the board's colour table.
All other colours are converted to black. Consequently you should use
the function as_GetNearestColor to set colours in the DC or pick a colour
directly from the colour table with as_GetBoardData/AS_DATA_COLORTABLE.

Since AniSprite passes a HDC to the callback, you can use any Windows GDI
function to draw into the sprite. For the same reason, and because of the
conversion from DIB to DDB and vice versa, DDB callbacks are relatively
slow.

Syntax:  DWORD asCallBack(ASPRITE Sprite, int Event, DWORD Value, LPVOID
                          Data)

         Sprite      The sprite handle.

         Event       Always AS_EVENT_PAINT_DDB.

         Value       Always zero.

         Data        A pointer of type ASPAINT_DDB. This is a pointer to a
                     structure with the following elements:
                     hDC         The display context.
20  ---  Callback functions                                   ITB CompuPhase

                     Width       The width of the sprite.
                     Height      The height of the sprite.

Returns: The return value should be zero.


DIB Callback functions

Callback functions that use the internal 8-bpp DIB format don't need prepa-
ration before they are called and are consequently fast. Windows GDI cannot
be used for graphical operations.

Syntax:  DWORD asCallBack(ASPRITE Sprite, int Event, DWORD Value, LPVOID
                          Data)

         Sprite      The sprite handle.

         Event       Always AS_EVENT_PAINT_DIB.

         Value       Always zero.

         Data        A pointer of type ASPAINT_DIB. This is a pointer to a
                     structure with the following elements:
                     lpBitsInfo  Pointer to a BITMAPINFO structure that
                                 describes the DIB image bits.
                     lpBits      Pointer to the board image bits in 8-bpp
                                 DIB format. This image is in construction.
                                 That is, it has been build from background
                                 image and layered sprites below the current
                                 sprite. After this callback function
                                 other sprites may be painted on top of
                                 it. Possibly this sprite may even not be
                                 visible at all. (See also page  8.)
                     X, Y        Position of the sprite in the scratch
                                 image. This position refers the the lower
                                 left corner of the sprite.
                     Width,
                     Height      Dimensions of the sprite rectangle.
                     cX, cY      Position of the clip rectangle in the
                                 scratch image. The position refers to the
                                 lower left corner. The clip rectangle is
                                 the part of the sprite that needs updating.
                     cWidth,
AniSprite                                        Callback functions  ---  21

                     cHeight     Dimensions of the clip rectangle.

Returns: The return value should be zero.


Timer callback

When you forward timer messages to AniSprite with as_ForwardMessage, any
sprite that has installed a timer callback receives the AS_EVENT_TIMER
event.

Syntax:  DWORD asCallBack(ASPRITE Sprite, int Event, DWORD Value, LPVOID
                          Data)

         Sprite      The sprite handle.

         Event       Always AS_EVENT_TIMER.

         Value       Always zero.

         Data        Always zero.

Returns: The return value should be zero.


Collision callback

Function as_ForwardMessage checks collisions between sprites at the final
stage of its timer tick processing. In other words, after every sprite has
received the AS_EVENT_TIMER message, the function sends the AS_EVENT_COLLIDE
event to every sprite that touches another sprite in the same layer.

The concept of "touching" depends on the opaque levels of both sprites,
see page  6 for details.

Both sprites receive the event (if both have installed the collision call-
back) and each receives a handle of the other.

Syntax:  DWORD asCallBack(ASPRITE Sprite, int Event, DWORD Value, LPVOID
                          Data)

         Sprite      The sprite handle.

         Event       Always AS_EVENT_COLLIDE.
22  ---  Tips for optimizing AniSprite                        ITB CompuPhase

         Value       Always zero.

         Data        The handle of the sprite that this sprite touches.

Returns: The return value should be zero.


Mouse events callback

When you forward mouse messages to AniSprite with as_ForwardMessage, any
sprite that has installed a mouse event callback receives the AS_EVENT_MOUSE
event. A hidden sprite does not receive any mouse notifications.

Syntax:  DWORD asCallBack(ASPRITE Sprite, int Event, DWORD Value, LPVOID
                          Data)

         Sprite      The sprite handle.

         Event       Always AS_EVENT_MOUSE.

         Value       The mouse message, one of the following:
                       WM_LBUTTONDOWN
                       WM_LBUTTONUP
                       WM_RBUTTONDOWN
                       WM_RBUTTONUP
                       WM_MOUSEMOVE
                       WM_MOUSELEAVE

         Data        A pointer to a POINT structure that holds the coordi-
                     nates of the mouse pointer, relative to the sprite's
                     origin. This parameter is NULL in the case of the
                     WM_MOUSELEAVE message.

Returns: The return value should be zero.



Tips for optimizing AniSprite

* Reduce memory usage
  By avoiding features that you may not need, you quickly reduce AniSprite's
  memory footprint. The most memory consuming operations are alpha level
  installation and large scratch areas.
AniSprite                                     A programming example  ---  23

  o 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.

  o minimal number of alpha/luma levels
    When all alpha 256 levels are installed, the memory usage is 256 times
    64 kBytes is 16 MBytes! Since the number of palette colours is only 256
    it is nearly 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.

    Luma levels take only 256 byte per level, so you don't have to worry to
    much about them. However, it is unlikely that the mask quality improves
    when installing more that 50 luma levels.

  o minimal mask type
    Cutout masks are the cheapest with respect to memory consumption. Luma
    masks need luma levels and alpha masks need alpha levels, which take 64
    kBytes each.

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

  o use an identity palette
    When the display is in a 256 colour resolution, Microsoft Windows
    performs better when you use an identity palette. as_SetPalette can
    create an identity palette for a board.



A programming example

This first example program creates a bouncing ball on a simple background.
The images are loaded from .BMP files; these are convenient, because the
format of a .BMP file closely resembles that of a DIB in memory.
24  ---  A programming example                                ITB CompuPhase

----------------------------------------------------------------------------
#include <windows.h>
#include "..\anispri.h"

#define BOARD_WIDTH     640
#define BOARD_HEIGHT    480
#define TIMER_INTERVAL  50

LRESULT CALLBACK AnimWinFunc(HWND, unsigned, WPARAM, LPARAM);



int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                   LPSTR lpCmdLine, int nCmdShow)
{
  MSG msg;
  WNDCLASS wc;
  RECT rect;
  DWORD dwStyle;

  wc.style = NULL;
  wc.lpfnWndProc = (WNDPROC)AnimWinFunc;
  wc.cbClsExtra = 0;
  wc.cbWndExtra = 0;
  wc.hInstance = hInstance;
  wc.hIcon = LoadIcon(hInstance, (LPSTR)"anim_icon");
  wc.hCursor = LoadCursor(NULL, IDC_ARROW);
  wc.hbrBackground = GetStockObject(LTGRAY_BRUSH);
  wc.lpszMenuName = (LPSTR)NULL;
  wc.lpszClassName = "Animation";
  if (!RegisterClass(&wc))
    return FALSE;

  /* create a window with the right size for the board */
  SetRect(&rect, 0, 0, BOARD_WIDTH, BOARD_HEIGHT);
  dwStyle = WS_POPUPWINDOW | WS_CAPTION | WS_VISIBLE;
  AdjustWindowRect(&rect, dwStyle, FALSE);
  CreateWindow("Animation", "AniSprite: Example 1", dwStyle,
               50, 50, rect.right - rect.left, rect.bottom - rect.top,
               0, 0, hInstance, NULL);

  while (GetMessage(&msg, NULL, 0, 0)) {
    TranslateMessage(&msg);
AniSprite                                     A programming example  ---  25

    DispatchMessage(&msg);
  } /* while */

  return msg.wParam;
}



LRESULT CALLBACK AnimWinFunc(HWND hwnd, unsigned message,
                             WPARAM wParam, LPARAM lParam)
{
static ASBOARD Board;
static ASPRITE Sprite;
static int stepx, stepy;
  PAINTSTRUCT ps;
  HDC hdc;
  int x, y, width, height;

  switch (message) {
  case WM_CREATE:
    /* load the board, use "palette mode" for optimal performace */
    Board = as_LoadBoard("maze.bmp", AS_MODE_PAL_COLORS, NULL, NULL);
    /* load a sprite (with a cutout mask) */
    Sprite = as_Load("sprite1.bmp", PALETTERGB(0xff,0x00,0xff), NULL, NULL);

    /* assign and show the sprite */
    as_Assign(Sprite, Board, 0);
    as_Show(Sprite, TRUE);

    /* Create a timer to move the sprite, set initial direction */
    as_SetTimer(Board, hwnd, TIMER_INTERVAL);
    stepx = 5;
    stepy = 3;
    break;

  case WM_DESTROY:
    as_Assign(Sprite, Board, -1);
    as_Delete(Sprite, TRUE);
    as_DeleteBoard(Board, TRUE);
    PostQuitMessage(0);
    break;
26  ---  A programming example                                ITB CompuPhase

  case AS_TIMER:
    /* get current position */
    x = as_GetValue(Sprite, AS_VALUE_XPOS);
    y = as_GetValue(Sprite, AS_VALUE_YPOS);
    width = as_GetValue(Sprite,AS_VALUE_WIDTH);
    height = as_GetValue(Sprite,AS_VALUE_HEIGHT);

    /* Move the image around a bit, check against borders */
    x += stepx;
    y += stepy;
    if (x < 0) {
      x = 0;
      stepx = -stepx;
    } else if (x + width > BOARD_WIDTH) {
      x = BOARD_WIDTH - width;
      stepx = -stepx;
    } /* if */
    if (y < 0) {
      y = 0;
      stepy = -stepy;
    } else if (y + height > BOARD_HEIGHT) {
      y = BOARD_HEIGHT - height;
      stepy = -stepy;
    } /* if */

    as_SetPos(Sprite, x, y);

    /* repaint the board */
    hdc = GetDC(hwnd);
    as_PaintBoard(hdc, Board, 0, 0, FALSE);
    ReleaseDC(hwnd, hdc);
    break;

  case WM_PAINT:
    hdc=BeginPaint(hwnd, &ps);
    as_PaintBoard(hdc, Board, 0, 0, TRUE);
    EndPaint(hwnd, &ps);
    break;

  case WM_ERASEBKGND:
  case WM_PALETTECHANGED:
  case WM_QUERYNEWPALETTE:
AniSprite                                     A programming example  ---  27

    return as_ForwardMessage(Board, hwnd, message, wParam, lParam);

  default:
    return DefWindowProc(hwnd, message, wParam, lParam);
  } /* switch */

  return 0L;
}
----------------------------------------------------------------------------
Figure 8: Minimal example

As it turns out, even the "minimal" example is fairly large. However,
much of the code deals with the general requirements of a Microsoft Windows
application, such as setting up a window or handling messages.

* WinMain creates a window class and a window with the requested client area
  size. Then it drops into the standard message loop.

* AnimWinFunc sets up the animation board in the WM_CREATE handling code,
  according to the steps starting at page page  13. It also installs a timer
  to keep the animation going. The AS_TIMER message handling is the part
  where the sprite is actually animated. Upon exit, the WM_DESTROY message
  executes the board cleanup, following the steps at page page  14.

The source code for this example is found in the "EXAMPLES" subdirectory
of the directory where AniSprite was installed. The file is called CUTOUT.C.
The directory contains more independent programming examples that illus-
trate, amongst others, alpha blending, callback functions and background
scrolling.
28  ---  Function reference                                   ITB CompuPhase

                             Function reference

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

This chapter lists all AniSprite functions and data structures. 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, I left out the word Sprite in most
function names that operate on 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 in a HDC.

With one exception (as_LastError), all functions set and reset the last
error code. Function as_LastError retrieves the last error for a sprite or a
board, without resetting the last error code.

The calling convention is not shown in the function prototypes, because it
differs between the 16-bit and 32-bit DLLs. For the 16-bit DLL it is "FAR
PASCAL". For the 32-bit DLL it is "__declspec(dllimport) __stdcall".


============================================================================
as_AllocResource                                             Allocate memory

as_AllocResource allocates a memory block. Using this function for memory
allocation makes the memory management easier, because you will not need to
make a difference between pointers allocated by AniSprite functions (which
need to be released with as_FreeResource) and pointers allocated by malloc
(for which you must call free). Suppose you create an animation, which
contains some sprites that have a mask that you load from disk and others
have a mask that you calculate with as_CreateMask. When you finally want to
delete the sprites, you have to take care to use the right free functions
for freeing the masks.

Another use of as_AllocResource is for installing pre-calculated alpha
levels, that are saved on disk. In 16-bit mode AniSprite requires zero-
offset pointers for alpha levels. With as_AllocResource you can allocate
proper 64 kBytes memory blocks to load the alpha levels in to.
AniSprite                                                as_Animate  ---  29

Syntax:  LPVOID as_AllocResource(long Size)

         Size        The size of the requested memory block.

Returns: Returns a 32-bit pointer to the memory block, or NULL on failure.

Errors:  AS_ERR_MEMORY

Notes:   The memory resource must be deleted with as_FreeResource.

See also:as_FreeResource, as_SetBoardData/AS_DATA_ALPHA_LEVEL



============================================================================
as_Animate                                         Change the sprites bitmap

as_Animate gives the sprite a new appearance. The sprite's image, its size
and its mask type may change. 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 MaskBits, int MaskCode,
                         LPVOID ImageBits, BOOL ImageMasked,
                         LPRECT BoundingBox)

         Sprite      Identifies the sprite.

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

         MaskBits    The mask bits in 8-bpp DIB format. When the sprite does
                     not have a mask, (see MaskCode) the MaskBits parameter
                     is ignored.

         MaskCode    The MaskCode indicates the type of mask that is sup-
                     plied. It can be any of the following values:
                     * AS_MASK_NONE
                     * AS_MASK_CUTOUT
                     * AS_MASK_LUMA
                     * AS_MASK_ALPHA
30  ---  as_Animate                                           ITB CompuPhase

         ImageBits   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 in-
                     memory image blitting.

         BoundingBox
                     The bounding box of the opaque parts of the new image.
                     If set to NULL, the bounding box is set to the size
                     of the sprite. (See the "notes" below for more
                     information.)

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_INVALIDCODE,
         AS_ERR_UNSUPPORTED.

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. To reduce
         the blitting area a bounding rectangle may be given, which marks
         the differences between the old and the new image. This is espe-
         cially useful, when playing a (frame/cel) animation in a sprite
         that uses differential encoding between sequential images (1). Images
         in a frame animation file format frequently have large transparent
         margins on all sides. Differential encoding algorithms usually mark
         the image area that changes from one image to the next.

         The image bits should be based to the same palette as the one the
         board is created with.

See also:as_Create, as_Move, as_PaintBoard, as_SetPos

-----------------------------
  1  This refers to our companion product EGI.
AniSprite                                            as_BlitInBoard  ---  31

============================================================================
as_Assign                                         Assign a sprite to a board

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 (this constant
is defined in the standard header file LIMITS.H. Initially all levels are
empty. Sprites may be reassigned within the same board to a different level
and assignments may be cancelled.

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

         Sprite      Identifies the sprite.

         Board       Identifies the board.

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

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_BOARDMISMATCH,
         AS_ERR_INVALIDCODE,
         AS_ERR_UNASSIGNED,
         AS_ERR_UNSUPPORTED.

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

See also:as_GetValue/AS_VALUE_LAYER, as_GetBoardData/AS_DATA_SPRITE



============================================================================
as_BlitInBoard                          BitBlt directly into the board image

as_BlitInBoard copies a DIB directly into the board. This can be used, for
example, to tile a board with a seamless tile image.

Syntax:  BOOL as_BlitInBoard(ASBOARD Board,
                             int dstX, int dstY,
                             int Width, int Height,
                             LPBITMAPINFO BitsInfo,
                             LPVOID MaskBits, int MaskCode,
                             LPVOID ImageBits,
                             int srcX, int srcY)
32  ---  as_BoardFromBitmap                                   ITB CompuPhase

         Board       The board to blit the image in.

         dstX,
         dstY        Coordinates in the board image where to blit the DIB.

         Width,
         Height      The width and height of the section to blit.

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

         MaskBits    Pointer to the mask values in 8-bpp DIB format, or NULL
                     for no mask.

         MaskCode    The mask type, one of the values:
                     * AS_MASK_NONE
                     * AS_MASK_CUTOUT
                     * AS_MASK_LUMA
                     * AS_MASK_ALPHA

         ImageBits   Pointer to the image pixels in 8-bpp DIB format.

         srcX,
         srcY        The position in the source DIB of the upper left corner
                     of the rectangle to blit.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_WRONG_FORMAT.

See also:as_CreateBoard, as_ReplaceBoard



============================================================================
as_BoardFromBitmap             Create a board from a device dependent bitmap

as_BoardFromBitmap creates a board from a device dependent bitmap (DDB), by
converting the DDB into a DIB.

Syntax:  ASBOARD as_BoardFromBitmap(HDC hDC, HBITMAP hbmp,
                                    LPRGBQUAD Palette,
                                    int NumColors, int Code)
AniSprite                                            as_BoundingBox  ---  33

         hDC         A display device context handle, obtained (for example)
                     by GetDC. The logical palette that goes with the
                     device dependent bitmap must be selected in the device
                     context.

         hbmp        The handle to the device dependent bitmap.

         Palette     The colour table that the board should use (see notes).

         NumColors   The number of entries in the colour table that Palette
                     points to.

         Code        The properties of the board, see as_CreateBoard for
                     more information.

Returns: The board handle, or NULL on failure.

Errors:  AS_ERR_MEMORY,
         AS_ERR_INVALIDPOINTER

Notes:   A device dependent bitmap does not hold palette or colour informa-
         tion (which is more or less why it is called "device dependent").
         The DDB therefore depends on a palette in a device context. A board
         contains a colour table and the board's colour table is not neces-
         sarily equal to the DDB's palette. That is why you have to select
         both a logical palette and a colour table.

         If the Code parameter has the flag AS_MODE_PAL_COLORS set, this
         function already calls as_SetPalette for the board. Note that
         NumColors must be 256 in this case.

See also:as_CreateAlphaLevel, as_CreateBoard, as_CreateBoardWindow,
         as_CreateLumaLevel, as_DeleteBoard, as_GrabScreen



============================================================================
as_BoundingBox                     Return the smallest bounding box of a DIB

as_BoundingBox returns the smallest rectangle for a DIB that holds the
"image" of that DIB, while ignoring the "transparent" colour. This
function can be used both on the "face" picture of a sprite, or on the
mask of the sprite.
34  ---  as_Collide                                           ITB CompuPhase

Syntax:  BOOL as_BoundingBox(int Width, int Height,
                             LPVOID ImageBits, int Level,
                             LPRECT rc)

         Width,
         Height      The dimensions of the DIB.

         ImageBits   A pointer to the source picture.

         Level       The byte value in the source picture that is considered
                     to be transparent. If ImageBits points to the DIB of a
                     mask of a sprite, Level is typically 255. If ImageBits
                     points to the "face" picture of a sprite, the Level
                     argument should be set to the palette index of the
                     transparent colour.

         rc          The coordinates of the bounding box will be stored in
                     this parameter.

Returns: TRUE on success, FALSE on error.

Errors:  AS_ERR_WRONGFORMAT.

Notes:   You typically use this function before cropping the DIBs for the
         mask and the face picture of a sprite.

         If the sprite or the mask is fully transparent, all fields in
         parameter rc are zero upon return.

See also:as_CropImage, as_LevelImMask



============================================================================
as_Collide                        Check whether a sprites "touches" another

as_Collide detects whether a sprite collides with another sprite returns
that other sprite if so. Only visible sprites are considered; a collision is
defined as a non-empty intersection of the opaque parts of the sprites.

Syntax:  ASPRITE as_Collide(ASPRITE Sprite, BOOL SameLayer)

         Sprite      Identifies the sprite.
AniSprite                                             as_CollideBox  ---  35

         SameLayer   If TRUE, only sprites in the same layer as the identi-
                     fied sprite are checked for collisions. If FALSE, all
                     sprites on the board are checked.

Returns: The first colliding sprite, or NULL if no collision exists.

Errors:  AS_ERR_UNASSIGNED.

Notes:   See as_SetValue to set the "opaque level" of a sprite.

         Look up "Callback functions" in the index for an event-driven
         collision detection method.

See also:as_CollideBox, as_CollideSprite, as_GetValue/AS_VALUE_LAYER,
         as_PtInSprite, as_SetValue/AS_VALUE_OPAQUE_LEVEL



============================================================================
as_CollideBox                        Check whether a sprite is outside a box

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 Box)

         Sprite      Identifies the sprite.

         Box         Gives box position and dimensions.

Returns: TRUE if the sprite collides with the box and FALSE otherwise.

Errors:  AS_ERR_UNASSIGNED.

Notes:   as_CollideBox detects collisions regardless the current visibility
         state and layer of the sprite.

         See as_SetValue to set the "opaque" level of a sprite.

         This function check whether the sprite is outside a box. To verify
         whether a sprite is inside a box, use as_InBox.

See also:as_Collide, as_CollideSprite, as_GetValue/AS_VALUE_LAYER, as_InBox,
         as_SetValue/AS_VALUE_OPAQUE_LEVEL
36  ---  as_CollideSprite                                     ITB CompuPhase

============================================================================
as_CollideSprite                          Check whether two sprites "touch"

as_CollideSprite detects if the two sprites collide, regardless of the
layers that they are in and/or the current visibility state. A collision is
defined as a non-empty intersection of the opaque parts of the sprites.

Syntax:  BOOL as_CollideSprite(ASPRITE Sprite1, ASPRITE Sprite2)

         Sprite1,
         Sprite2     Sprite identifiers.

Returns: TRUE if the sprites collide and FALSE otherwise.

Errors:  AS_ERR_UNASSIGNED.

Notes:   See as_SetValue to set the "opaque level" of a sprite.

See also:as_Collide, as_CollideBox, as_GetValue/AS_VALUE_LAYER,
         as_PtInSprite, as_SetValue/AS_VALUE_OPAQUE_LEVEL



============================================================================
as_ConvertImage               Map a DIB to another palette or bit resolution

as_ConvertImage converts an image to a 8-bpp DIB image using a given colour
palette. Any image that is not in 8-bpp format must be converted before it
can be used in AniSprite. The input image must either be an 8-bpp DIB or a
16-bpp DIB; as_ConvertImage cannot convert "true colour" (or 24-bpp) DIBs.

Syntax:  LPVOID as_ConvertImage(LPBITMAPINFO SrcInfo,
                                LPVOID SrcBits,
                                LPBITMAPINFO DstInfo,
                                LPRGBQUAD Palette,
                                BOOL DeleteSrc)

         SrcInfo     Pointer to a BITMAPINFO structure that describes the
                     source image bits.

         SrcBits     Pointer to the source image bits. The source image may
                     be in 1-bpp, 4-bpp and 8-bpp format.
AniSprite                                                 as_Create  ---  37

         DstInfo     Pointer to a BITMAPINFO structure that is filled in by
                     as_ConvertImage. This parameter may be set to NULL; it
                     may also point to the same structure as SrcInfo.

         Palette     Pointer to an array with 256 RGBQUAD structures de-
                     scribing the palette colours to adjust the image to.

         DeleteSrc   If TRUE, the function frees the original source bitmap
                     that SrcBits points to. If set to TRUE, the memory
                     resource for SrcBits must have been allocated with an
                     AniSprite function.

Returns: Returns a 32-bit pointer to the resulting image bits memory block,
         or NULL on failure.

Errors:  AS_ERR_MEMORY,
         AS_ERR_WRONGFORMAT.

Notes:   as_ConvertImage cannot convert true colour (24-bpp) images. HiColor
         images (16-bpp) are supported, with the limitation that all colours
         in the source image that are not available in the specified palette
         are converted to black. The support for 16-bpp DIB conversion is
         intended for screen grabs. An application note on this subject is
         available, see appendix D for more information.

         as_ConvertImage does not modify the source bits. Instead it creates
         a new bitmap. The allocated memory resource must be deleted with
         as_FreeResource.

         If the function fails (it cannot allocate sufficient memory for the
         conversion) and you selected to delete the source image bits, the
         function does free SrcBits.

See also:as_FreeResource



============================================================================
as_Create                                                    Create a sprite

as_Create creates a new sprite. Initially the sprite is hidden (invisible)
and its position is (0, 0). Before a sprite can be moved or shown, it must
be assigned to a board.
38  ---  as_Create                                            ITB CompuPhase

Syntax:  ASPRITE as_Create(int Width, int Height,
                           LPVOID MaskBits, int MaskCode,
                           LPVOID ImageBits, BOOL ImageMasked)

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

         MaskBits    The mask bits in 8-bpp DIB format. When the sprite does
                     not have a mask, (see MaskCode) the MaskBits parameter
                     is ignored.

         MaskCode    The MaskCode indicates the type of mask that is sup-
                     plied. It can be any of the following:
                     * AS_MASK_NONE
                     * AS_MASK_CUTOUT
                     * AS_MASK_LUMA
                     * AS_MASK_ALPHA

         ImageBits   A pointer to the image bits in 8-bpp DIB format. If
                     the sprite has no image this pointer may be NULL. A
                     NULL image in combination with a luma mask delivers
                     a spotlight or shadow effect. Alpha masks must have
                     an image, as there must be something to blend the
                     background with. If a cutout mask sprite doesn't have
                     an image, it makes a black hole in the background.

         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 in-
                     memory image blitting. For other mask types, there
                     is no speed advantage for pre-masking the transparent
                     areas of the sprite image.

Returns: A sprite handle, or NULL on failure.

Errors:  AS_ERR_INVALIDCODE,
         AS_ERR_MEMORY.
AniSprite                                       as_CreateAlphaLevel  ---  39

Notes:   The sprite must be deleted with as_Delete.

         The image bits should refer to the same palette as the one the
         board is created with. You can adapt an image to a different
         palette with as_ConvertImage.

See also:as_Assign, as_ConvertImage, as_CreateMask, as_Delete, as_Load



============================================================================
as_CreateAlphaLevel                    Create an alpha blending lookup table

This function creates an alpha level, that can be installed in a board that
supports alpha blending.

Syntax:  LPVOID as_CreateAlphaLevel(LPRGBQUAD Palette,
                                    WORD InterFactor)

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

                     To retrieve an empty alpha level, Palette must be set
                     to NULL. In that case the InterFactor is ignored. An
                     empty alpha level is not initialized.

         InterFactor The InterFactor gives the translucency factor for the
                     blended colour. InterFactor 0 means opaque colour and
                     256 means transparent colour. Values in between mix
                     sprite (foreground) and background proportionally.

Returns: Returns a 32-bit pointer to a 64 kBytes memory block, or NULL on
         failure.

Errors:  AS_ERR_MEMORY.

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 the
         Palette parameter set to NULL. This is especially useful in 16-bit
         mode, because the alpha level pointer must have an offset portion
         that is zero (see as_SetBoardData).

         This memory resource must be deleted with as_FreeResource.
40  ---  as_CreateBitmapInfoHeader                            ITB CompuPhase

See also:as_CreateLumaLevel, as_FreeResource, as_GetBoardData,
         as_SetBoardData


============================================================================
as_CreateBitmapInfoHeader                    Fill in a common data structure

as_CreateBitmapInfoHeader fills in a BITMAPINFO structure. It calculates
most fields from the passed in parameters or from default values. This
function is convenient when creating a board or a sprite that is not based
on an image that is loaded from disk.

Syntax:  void as_CreateBitmapInfoHeader(LPBITMAPINFO BitsInfo, int Width,
                                        int Height, LPRGBQUAD Palette,
                                        int Colors)

         BitsInfo    A pointer to the BITMAPINFO structure that will contain
                     the settings according to the remaining parameters.

         Width,
         Height      The size of the image to which this BITMAPINFO struc-
                     ture refers.

         Palette     The colour table that is copied into the BITMAPINFO
                     structure.

         Colors      The number of entries in Palette.

See also:as_CreateBoard



============================================================================
as_CreateBoard                                     Create an animation board

as_CreateBoard creates an animation area. All sprite animation takes place
on a board. The number of sprites that animate on a board is unlimited,
although animation the speed will decrease with a high number of sprites. A
board is based on a background image and it has colour information for the
board image and for all sprites that are assigned 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.
AniSprite                                            as_CreateBoard  ---  41

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

Syntax:  ASBOARD as_CreateBoard(LPBITMAPINFO BitsInfo,
                                LPVOID ImageBits,
                                LPRECT VisRect, int Code)

         BitsInfo    Pointer to a BITMAPINFO structure that describes the
                     DIB image bits and the colour table.

         ImageBits   Pointer to the image bits in 8-bpp DIB format. If this
                     parameter is NULL, the function creates a black board.

         VisRect     Part of the image bits that is used as visible board.
                     If VisRect is NULL, the board dimension are taken from
                     the BitsInfo parameter; that is, the board size equals
                     the image size.

         Code        Code describes the board capabilities. These capabili-
                     ties are a combination of the following:

                     * AS_MODE_ALPHA
                       Prepare the board for alpha blending support.

                     * AS_MODE_DIBSECTION
                       Use a DIB section to draw the board onto the display.
                       Blitting a DIB section is often faster than the GDI
                       function StretchDIBits. DIB sections are available
                       in Microsoft Windows 95 and Windows NT. This flag
                       is silently ignored when AniSprite detects that the
                       Windows version does not provide DIB sections.

                     * AS_MODE_INCRHIDE
                       Sets the "show/hide" operations to be incremental.
                       See as_Show on page  81 for details.

                     * AS_MODE_LUMA
                       Prepare the board for luma blending support.
42  ---  as_CreateBoard                                       ITB CompuPhase

                     * AS_MODE_MASKED
                       Create a masked board. A masked board may not contain
                       an image (so ImageBits must be NULL) and it can
                       only support sprites with cutout masks. The "DIB
                       section" may not be set either.

                     * AS_MODE_NODRAW
                       as_PaintBoard will update the internal (in-memory)
                       representation of the board and all sprites, but it
                       will skip the last step of displaying the assembled
                       image on the screen.

                     * AS_MODE_PAL_COLORS
                       Use palette colours when blitting, i.e. AniSprite may
                       assume that the palette in the BITMAPINFO structure
                       is always realized during as_PaintBoard. This as-
                       sumption is valid when you call as_SetPalette to make
                       the palette for the board. Blitting with "palette
                       colour" mode is faster than standard mode.

Returns: The board handle, or NULL on failure.

Errors:  AS_ERR_MEMORY,
         AS_ERR_WRONGFORMAT.

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 VisRect parameter to optimize the size of the
         visible board area.

         A masked board contains no image, but it keeps a mask for the
         board. This "board mask" contains the masks of all sprites. This
         feature allows you to paint sprites on top of a background that
         is drawn by other means. For example, one may use masked boards to
         move 256-colour sprites on top of a grabbed image if the display is
         in RGB mode.

See also:as_BoardFromBitmap, as_CreateAlphaLevel,
         as_CreateBoardWindow, as_CreateLumaLevel, as_DeleteBoard,
         as_GrabImage, as_LoadBoard, as_SetPalette
AniSprite                                      as_CreateBoardWindow  ---  43

============================================================================
as_CreateBoardWindow               Create a palette aware window for a board

as_CreateBoardWindow creates a "board window" that automatically handles
some aspects of board redrawing.

Syntax:  HWND as_CreateBoardWindow(ASBOARD Board, LPCSTR Caption,
                                   DWORD dwStyle, int x, int y,
                                   HWND hwndParent, int reserved)

         Board       The board handle.

         Caption     The text to put in the caption. The window style should
                     include the "WS_CAPTION" style (see the Windows SDK
                     reference).

         dwStyle     The window style, see the standard Windows function
                     CreateWindow for more information. Set this field to
                     zero (0) to create a standard "child" window.

         x, y        The position of the upper left corner of the window in
                     pixels. For child windows, this position is relative to
                     its parent window. For popup and overlapped windows, it
                     is the screen position.

         hwndParent  The parent window, or NULL if none. The parent window
                     may not be NULL for a child window.

         reserved    Reserved for future extension, should be set to zero.

Returns: The window handle of the created window, or NULL on failure.

Notes:   The size (width x height) of the client area window is the same as
         that of the board.

         The board window is deleted when the board is deleted itself.

         If a palette is attached to the board (see as_SetPalette), the
         board window automatically sets and refreshes the palette when
         needed.

See also:as_BoardFromBitmap, as_CreateBoard, as_DeleteBoard.
44  ---  as_CreateLumaLevel                                   ITB CompuPhase

============================================================================
as_CreateLumaLevel                       Create a luma blending lookup table

This function creates an luma level, which can be installed in a board
that supports luma blending. Originally, luma blending is the adjustment of
the brightness (luminance) of all image data below the mask of the current
sprite. AniSprite supports blending to coloured light, which makes "luma
blending" a more general technique.

Syntax:  LPVOID as_CreateLumaLevel(LPRGBQUAD Palette,
                                   COLORREF crColor,
                                   WORD InterFactor)

         Palette     Address of an array with 256 RGBQUAD's defining a 256
                     colour palette. A brightness level lookup table is
                     calculated from this palette.

                     To retrieve an empty brightness level, Palette must be
                     set to NULL. In that case the parameters crColor and
                     Interfactor are ignored. An empty brightness level is
                     not initialized.

         crColor     The colour to blend towards, usually black for shadows
                     and white for flare effects.

         InterFactor The InterFactor gives the position on the scale between
                     each colour in Palette and the blend color crColor.
                     An InterFactor of 0 means leaves every colour in
                     Palette unaltered and 256 sets each entry in Palette
                     to crColor. Values in between mix between the two
                     extremes.

Returns: Returns a 32-bit pointer to a 256 bytes memory block, or NULL on
         failure.

Errors:  AS_ERR_MEMORY.
AniSprite                                             as_CreateMask  ---  45

Notes:   For each palette colour, as_CreateLumaLevel calculates a new colour
         by interpolating the RGB components of each palette entry and of
         the blend colour, under control of the interpolation factor. 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.

         This memory resource must be deleted with as_FreeResource.

See also:as_FreeResource, as_GetBoardData, as_SetBoardData



============================================================================
as_CreateMask                                                  Create a mask

as_CreateMask creates a mask for a sprite image. The values in the returned
DIB image bits range from 0 to 255. In general, 0 means opaque and 255 means
transparent (see notes).

Syntax:  LPVOID as_CreateMask(LPBITMAPINFO BitsInfo,
                              LPVOID ImageBits, BOOL MaskImage,
                              COLORREF FAR *crTransColor,
                              int Colors)

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

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

         MaskImage   Boolean that indicates whether the transparent parts
                     in the source image should be masked out. Sprites
                     with masked out images can be blitted faster to the
                     in-memory buffer.
46  ---  as_CropImage                                         ITB CompuPhase

         crTransColor
                     Address of an array with the colours that are consid-
                     ered more or less transparent. The order of the colours
                     in the array determines to which alpha or luma level
                     each colour maps (see notes below).

                     Colours in the crTransColor array can be either RGB
                     values or palette indexes and can be set with the
                     macros PALETTERGB or PALETTEINDEX respectively. If the
                     colour is a RGB value AniSprite looks for the palette
                     index in the given palette itself.

         Colors      Number of elements in the crTransColor array.

Returns: Returns a 32-bit pointer to the mask bits memory block.

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

Errors:  AS_ERR_OPAQUE,
         AS_ERR_MEMORY,
         AS_ERR_WRONGFORMAT.

Notes:   Masks created with as_CreateMask can be used as image mask for
         a sprite, either to create a new sprite with or to animate an
         existing one.

         The last colour in the crTransColor array always maps to mask value
         255 (transparent). All other colours map to the mask values 1,
         2,...,(Colors-1). You will need to install luma or alpha blend-
         ing tables for these mask values. Any colour that is not in the
         crTransColor list is mapped to mask value 0 (opaque).

         This memory resource must be deleted with as_FreeResource.

See also:as_Animate, as_Create, as_ReduceMask,
         as_SetBoardData/AS_DATA_ALPHA_LEVEL & AS_DATA_LUMA_LEVEL,
         as_SmoothMask


============================================================================
as_CropImage                                   Crop off the margins of a DIB

as_CropImage crops off the margins of a DIB. One typically uses this func-
tion to cut off fully transparent borders from the face and the mask of a
sprite.
AniSprite                                                 as_Delete  ---  47

Syntax:  LPVOID as_CropImage(LPBITMAPINFO SrcInfo, LPVOID SrcBits,
                             LPBITMAPINFO DstInfo, LPRECT rc,
                             BOOL DeleteSrc)

         SrcInfo     The BITMAPINFO header for the original DIB.

         SrcBits     The pixel data for the original DIB.

         DstInfo     Upon return, this BITMAPINFO header will hold the
                     updated information for the modified DIB. This argument
                     may be NULL.

         rc          The rectangle that specifies the area in the original
                     DIB that you want to keep.

         DeleteSrc   If TRUE, this function deletes the source picture
                     after conversion. In this case, the memory resource
                     for SrcBits must have been allocated with an AniSprite
                     function.

Returns: Returns a 32-bit pointer to the resulting image bits memory block,
         or NULL on failure.

Errors:  AS_ERR_INVALIDCRDS,
         AS_ERR_MEMORY,
         AS_ERR_WRONGFORMAT.

Notes:   Function as_BoundingBox returns the rectangle that forms the
         smallest bounding box of a sprite. This rectangle can then be fed
         into this function.

See also:as_BoundingBox, as_ConvertImage, as_FreeResource, as_ScaleDIB



============================================================================
as_Delete                                                    Delete a sprite

as_Delete deletes a sprites, that is no longer used.

Syntax:  BOOL as_Delete(ASPRITE Sprite, BOOL DeleteDIBs)

         Sprite      The sprite handle.
48  ---  as_DeleteBoard                                       ITB CompuPhase

         DeleteDIBs  If TRUE, as_Delete also deletes the image and the mask
                     DIBs using as_FreeResource.

Returns: TRUE on success and FALSE if the sprite is still assigned to a
         board.

Errors:  AS_ERR_ASSIGNED.

Notes:   A sprite should be detached from the board with as_Assign before
         deletion.

         as_Delete can only free the sprite image and mask if their memory
         blocks were allocated with AniSprite functions (as_AllocResource,
         as_CreateMask, etc).

See also:as_Assign, as_Create, as_Load



============================================================================
as_DeleteBoard                                              Delete the board

as_DeleteBoard 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 sprites must be detached from it.

Syntax:  BOOL as_DeleteBoard(ASBOARD Board, BOOL DeleteDIB)

         Board       Identifies the board.

         DeleteDIB   If TRUE, as_DeleteBoard also frees the board image
                     using as_FreeResource.

Returns: Returns TRUE on success and FALSE on failure.

Errors:  AS_ERR_NOTEMPTY,

Notes:   A board that is deleted may not have any sprites assigned to its
         layers. They should be detached first with as_Assign.

         as_DeleteBoard can only free the board image if the image was cre-
         ated or allocated by an AniSprite function (like as_AllocResource).

         as_DeleteBoard also deletes a board window, if one was created for
         the board.
AniSprite                                              as_FillBoard  ---  49

See also:as_Assign, as_BoardFromBitmap, as_CreateBoard,
         as_CreateBoardWindow, as_FreeResource, as_LoadBoard


============================================================================
as_ExpandMonoMask                         Converts masks from 1-bpp to 8-bpp

Transforms a 1-bpp monochrome mask to a 8-bpp monochrome mask.

Syntax:  LPVOID as_ExpandMonoMask(int Width, int Height,
                                  LPVOID MonoBits)

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

         MonoBits    A pointer to the mask in 1-bpp format (i.e. 8 "mask
                     pixels" per byte).

Returns: Returns a 32-bit pointer to the mask bits memory block, or NULL on
         failure.

Errors:  AS_ERR_MEMORY.

Notes:   This memory resource must be deleted with as_FreeResource. Ani-
         Sprite uses 8-bpp masks exclusively.

         You need this function to interface AniSprite with EGI 1.2 (2) or
         earlier. EGI version 2.0 and later can create the 8-bpp masks that
         AniSprite requires.

See also:as_SmoothMask



============================================================================
as_FillBoard                                 Set the board to a solid colour

as_FillBoard sets the board, or a portion of the board, to a solid colour.

-----------------------------
  2  EGI is a CompuPhase product.
50  ---  as_ForwardMessage                                    ITB CompuPhase

Syntax:  BOOL as_FillBoard(ASBOARD Board, int X, int Y,
                           int Width, int Height, COLORREF crColor)

         Board       The board handle.

         X, Y        The coordinates of the upper left corner of the rectan-
                     gle to fill.

         Width,
         Height      The size of the rectangle to fill.

         crColor     The colour, as an index or in RGB format.

Returns: TRUE if the message was handled, FALSE otherwise.

Errors:  AS_ERR_INVALIDCRDS

Notes:   This function is typically used to clear the board completely, so X
         and Y are typically zero and Width and Height are set to the width
         and height of the board.

See also:as_BlitInBoard, as_CreateBoard



============================================================================
as_ForwardMessage                     Let AniSprite handle a Windows message

as_ForwardMessage handles a few messages on behalf of the application.

Syntax:  BOOL as_ForwardMessage(ASBOARD Board, HWND hWnd,
                                UINT msg, WPARAM wParam,
                                LPARAM lParam)

         Board       The board handle.

         hWnd        The window handle to which the message was sent.

         msg         The Windows 'message.

         wParam      Extra data related to the message.

         lParam      Extra data related to the message.

Returns: TRUE if the message was handled, FALSE otherwise.
AniSprite                                           as_FreeResource  ---  51

Notes:   Currently, the messages that you should forward are:
         * WM_ERASEBKGND if the window is completely covered by the board.
         * WM_PALETTECHANGED
         * WM_QUERYNEWPALETTE
         * WM_TIMER for timer callbacks and collision detection
         * AS_TIMER for timer callbacks and collision detection
         * AS_LBUTTONDOWN for mouse events
         * AS_LBUTTONUP for mouse events
         * AS_RBUTTONDOWN for mouse events
         * AS_RBUTTONUP for mouse events
         * AS_MOUSEMOVE for mouse events

         You only need to forward the palette messages if you set a palette
         for the board with as_SetPalette

See also:as_SetPalette



============================================================================
as_FreeResource                                         Frees a memory block

as_FreeResource deletes a resource, that was created by any AniSprite
function and that has no special delete function.

Syntax:  LPVOID as_FreeResource(LPVOID Resource)

         Resource    Pointer to the resource that is created by:
                     as_AllocResource,
                     as_ConvertImage,
                     as_CreateAlphaLevel,
                     as_CreateLumaLevel,
                     as_CreateMask,
                     as_CropImage,
                     as_ExpandMonoMask,
                     as_Load,
                     as_LoadBoard,
                     as_LoadDIB,
                     as_ScaleDIB.

Returns: Always returns NULL.
52  ---  as_GetBoardData                                      ITB CompuPhase

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

See also:as_ConvertImage, as_CreateAlphaLevel, as_CreateLumaLevel,
         as_CreateMask, as_Delete, as_DeleteBoard, as_ExpandMonoMask,
         as_Load, as_LoadBoard, as_LoadDIB, as_ScaleDIB



============================================================================
as_GetBoardData                               Return a pointer to board data

This function returns the address of some board related values.

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

         Board       Identifies the board.

         Code        Indicates which board data to retrieve. The code can be
                     any of the following:

                     * AS_DATA_ALPHA_LEVEL
                       A pointer to the alpha lookup table at mask level
                       Index.

                     * AS_DATA_BITMAPINFO
                       A pointer to the BITMAPINFO structure for the board.
                       The Index parameter should be zero.

                     * AS_DATA_BOX
                       Returns the visible area of the board image in a RECT
                       structure; see VisRect in as_CreateBoard. The Index
                       parameter should be zero.

                     * AS_DATA_CANVASBITS
                       A pointer to the "scratch" DIB data. Each board
                       also has a scratch DIB (see page  8). The Index
                       parameter should be zero.

                     * AS_DATA_COLORTABLE
                       A pointer to the colour table that the board uses in
                       RGBQUAD format. The Index parameter should be zero.
AniSprite                                           as_GetBoardData  ---  53

                     * AS_DATA_IMAGEBITS
                       A pointer to the board DIB data. The Index parameter
                       should be zero.

                     * AS_DATA_LUMA_LEVEL
                       A pointer to the luma lookup table at mask level
                       Index. This is a 256 byte long lookup table.

                     * AS_DATA_MASKBITS
                       For masked boards, a pointer to the DIB of the mask.
                       The Index parameter should be zero.

                     * AS_DATA_REGIONRECT
                       A pointer to a rectangle of the "update" region for
                       the board. Parameter Index indicates the requested
                       rectangle.

                     * AS_DATA_SPRITE
                       A pointer a sprite at position Index in the sprite
                       list. This allows you to walk through all sprites
                       that are attached to a board.

                     * AS_DATA_UPDATERECT
                       A pointer to the bounding box of all changes on the
                       board since the last call to as_PaintBoard. The Index
                       parameter should be zero.

                     * AS_DATA_USERDATA
                       Returns a pointer to "user data". The Index parame-
                       ter should be zero.

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

Returns: Returns the appropriate value pointer.

Errors:  AS_ERR_INVALIDCODE,
         AS_ERR_INVALIDINDEX,
         AS_ERR_UNSUPPORTED.

See also:as_GetBoardHandle, as_GetBoardValue, as_SetBoardData
54  ---  as_GetBoardHandle                                    ITB CompuPhase

============================================================================
as_GetBoardHandle                                      Return a board handle

This function returns board related values.

Syntax:  HANDLE as_GetBoardHandle(ASBOARD Board, int Code)

         Board       Identifies the board.

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

                     * AS_HANDLE_DIBSECTION
                       Returns the DIB section handle (a HBITMAP value).

                     * AS_HANDLE_PALETTE
                       Returns the palette handle that as_SetPalette cre-
                       ated. This is a HPALETTE type.

Returns: The requested handle, or NULL on failure.

Errors:  AS_ERR_INVALIDCODE.

Notes:   An application requests that AniSprite uses a DIB section by
         passing a flag to the as_CreateBoard function. The DIB section
         is created at the first call to as_PaintBoard. Until that first
         call, this function returns NULL for the HBITMAP handle for the DIB
         section.

See also:as_CreateBoard, as_GetBoardData, as_SetBoardValue,
         as_SetPalette



============================================================================
as_GetBoardValue                                    Return a board parameter

This function returns board related values.

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

         Board       Identifies the board.

         Code        Indicates which board value is to be retrieved. The
                     code can be any of the following:
AniSprite                                          as_GetBoardValue  ---  55

                     * AS_VALUE_HEIGHT
                       Returns the height of the animation board, which is
                       the height of visible part of the background image.
                       The Index parameter should be zero.

                     * AS_VALUE_MASKSUPPORT
                       Returns TRUE if the given mask type is supported by
                       the board. The Index parameter must be:
                       o AS_MASK_ALPHA
                       o AS_MASK_CUTOUT
                       o AS_MASK_LUMA

                     * AS_VALUE_NUMSPRITES
                       Returns the number of sprites assigned to the board
                       layer. The Index parameter is the layer number. To
                       retrieve the total number of sprites assigned to the
                       board, set Index to -1.

                     * AS_VALUE_PAL_COLORS
                       Returns TRUE if the board uses "palette colour"
                       mode. The Index parameter should be zero.

                     * AS_VALUE_TIMERRES
                       Returns the actual timer resolution that was set for
                       the board by as_SetTimer. The Index parameter should
                       be zero.

                     * AS_VALUE_VERSION
                       Returns the version of AniSprite. The Board and Index
                       parameters are ignored.

                     * AS_VALUE_WIDTH
                       Returns the width of the animation board, which is
                       the width of visible part background image. The Index
                       parameter should be zero.

                     * AS_VALUE_XPOS
                       Returns the x-coordinate of the left side of the
                       animation board. The Index parameter should be zero.

                     * AS_VALUE_YPOS
                       Returns the y-coordinate of the top side of the
                       animation board. The Index parameter should be zero.
56  ---  as_GetData                                           ITB CompuPhase

         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_ERR_INVALIDCODE,
         AS_ERR_INVALIDINDEX.

See also:as_GetBoardData, as_SetBoardValue



============================================================================
as_GetData                                   Return a pointer to sprite data

This function returns the pointers to sprite related data.

Syntax:  LPVOID as_GetData(ASPRITE Sprite, int Code, int Index)

         Sprite      Identifies the sprite.

         Code        Indicates which sprite value pointer is to be re-
                     trieved. The code can be any of the following:

                     * AS_DATA_BOARD
                       The board on to which the sprite is attached. The
                       Index parameter should be zero.

                     * AS_DATA_BOX
                       The bounding rectangle of the sprite (usually this
                       is the box around the complete sprite image); see
                       parameter BoundingBox in as_Animate. The Index
                       parameter should be zero.

                     * AS_DATA_CALLBACK
                       Returns a pointer to the requested callback function,
                       or NULL if the callback function is not installed.
                       Index must be one of the following:
                       o AS_EVENT_COLLIDE: Collision between sprites.
                       o AS_EVENT_PAINT_DDB: paint sprite, DDB format.
                       o AS_EVENT_PAINT_DIB: paint sprite, DIB format.
                       o AS_EVENT_TIMER: Periodic timer event.
AniSprite                                        as_GetNearestColor  ---  57

                       o AS_EVENT_MOUSE: Mouse event (click, move, leave).

                       See page  18 for more information on callback func-
                       tions.

                     * AS_DATA_IMAGEBITS
                       Returns a pointer to the image data in DIB format or
                       NULL if the sprite has no image. The Index parameter
                       should be zero.

                     * AS_DATA_LINK
                       Returns a pointer to the indexed sprite that is
                       linked to the specified sprite, or NULL if no (more)
                       sprite is linked to that sprite. The Index parameter
                       starts at zero (to acquire the first linked sprite).

                     * AS_DATA_MASKBITS
                       Returns a pointer to the mask data in DIB format, or
                       NULL if the sprite has no mask. The Index parameter
                       should be zero.

                     * AS_DATA_MASTER
                       Returns the sprite to which the identified sprite is
                       linked. The Index parameter should be zero.

                     * AS_DATA_USERDATA
                       Returns a pointer to "user data". The Index parame-
                       ter should be zero.

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

Returns: Returns the appropriate value pointer, or NULL on failure.

Errors:  AS_ERR_INVALIDCODE. AS_ERR_INVALIDINDEX.

See also:as_GetBoardData, as_GetValue, as_SetData



============================================================================
as_GetNearestColor                           Look up a colour in the palette

This function returns the colour (in RGB format) that is in the board's
colour table and that is closest to the given RGB colour.
58  ---  as_GetPaletteIndex                                   ITB CompuPhase

Syntax:  COLORREF as_GetNearestColor(ASBOARD Board,
                                     COLORREF crColor)

         Board       Identifies the board.

         crColor     The colour (in RGB format).

Returns: The color (in RGB format) of the closest match with the specified
         colour.

See also:as_GetPaletteIndex



============================================================================
as_GetPaletteIndex                           Look up a colour in the palette

This function returns the index in the boards's colour table whose colour is
closest to the given RGB colour.

Syntax:  as_GetPaletteIndex(ASBOARD Board, COLORREF crColor)

         Board       Identifies the board.

         crColor     The colour (in RGB format).

Returns: The index of the closest match with the specified colour.

See also:as_GetNearestColor



============================================================================
as_GetPos                                       Get the position of a sprite

as_GetPos returns the coordinates of a sprite on its board.

Syntax:  BOOL as_GetPos(ASPRITE Sprite, LPINT X, LPINT Y)

         Sprite      Identifies the sprite.

         X, Y        The coordinates at which the origin of the sprite are
                     stored in these two parameters.

Returns: TRUE on success, FALSE on failure.
AniSprite                                               as_GetValue  ---  59

Notes:   See as_SetOrigin to change the position of the origin in the
         sprite.

Errors:  AS_ERR_UNASSIGNED.

See also:as_SetOrigin, as_SetPos



============================================================================
as_GetValue                                        Return a sprite parameter

as_GetValue returns sprite related values.

Syntax:  int as_GetValue(ASPRITE Sprite, int Code)

         Sprite      Identifies the sprite.

         Code        Indicates which sprite value is to be retrieved. The
                     code can be any of the following:

                     * AS_VALUE_HEIGHT
                       The height of the sprite.

                     * AS_VALUE_ID
                       Returns the value that you set with as_SetValue.

                     * AS_VALUE_LAYER
                       Returns the layer that the sprite is attached to, or
                       -1 if the sprite is not attached to a board.

                     * AS_VALUE_MASKCODE
                       The type of the mask, any of the following:
                       o AS_MASK_ALPHA
                       o AS_MASK_CUTOUT
                       o AS_MASK_LUMA
                       o AS_MASK_NONE

                     * AS_VALUE_MASKED
                       Returns TRUE if the sprite image is pre-masked; see
                       as_Create for details.

                     * AS_VALUE_OPAQUE_LEVEL
                       The level at which a pixel in the sprite is consid-
                       ered "opaque".
60  ---  as_GrabScreen                                        ITB CompuPhase

                     * AS_VALUE_VERSION
                       Returns the version of AniSprite. The Sprite parame-
                       ter is ignored.

                     * AS_VALUE_VISIBLE
                       Returns TRUE if the sprite is visible.

                     * AS_VALUE_WIDTH
                       The width of the sprite.

                     * AS_VALUE_XORG
                       The horizontal offset of the origin of the sprite
                       from the left edge of the sprite.

                     * AS_VALUE_XPOS
                       Current x-coordinate of the sprite's origin, relative
                       to the left edge of the board image.

                     * AS_VALUE_YORG
                       The vertical offset of the origin of the sprite from
                       the top edge of the sprite.

                     * AS_VALUE_YPOS
                       Current y-coordinate of the sprite's origin, relative
                       to the upper left corner of the board image.

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

Errors:  AS_ERR_INVALIDCODE.

See also:as_GetData, as_SetOrigin, as_SetValue



============================================================================
as_GrabScreen                                               Do a screen grab

as_GrabScreen captures the current display contents, or a portion of the
display contents. The function returns the screen grab as a device dependent
bitmap (DDB).

Syntax:  HBITMAP as_GrabScreen(HDC hDC, LPRECT rc)
AniSprite                                         as_GrabSysPalette  ---  61

         hDC         The device context the grab. The logical palette to map
                     the device dependent bitmap to must be selected in this
                     device context.

         rc          The rectangle that contains the area of the screen to
                     grab, or NULL to grab the entire screen.

Returns: A handle to a device dependent bitmap, or NULL on failure.

Notes:   To obtain the current system palette (the palette that contains the
         colours currently displayed), use as_GrabSysPalette.

         To create a board from the grabbed screen, use as_BoardFromBitmap.

See also:as_BoardFromBitmap, as_GrabSysPalette



============================================================================
as_GrabSysPalette                        Retrieve the current system palette

as_GrabSysPalette captures the current system palette. It returns a palette
handle suitable to select in a device context (hDC) and it optionally fills
in a colour table with the format that AniSprite functions require.

Syntax:  HPALETTE as_GrabSysPalette(LPRGBQUAD Palette)

         Palette     A pointer to a colour table with 256 entries. Display
                     devices that support palettes (under Microsoft Windows)
                     are always 256-colour modes. The parameter may be NULL.

Returns: A handle to a logical palette.

Notes:   This function can also be used if the display is in an RGB mode, in
         which case it returns a default palette.

         The palette created by this function is always an identity palette.

See also:as_GrabScreen
62  ---  as_InBox                                             ITB CompuPhase

============================================================================
as_InBox                              Check whether a sprite is inside a box

as_InBox determines whether the sprite is completely inside a box. That is,
it verifies whether there are opaque parts of the sprite outside the box.

Syntax:  BOOL as_InBox(ASPRITE Sprite, LPRECT Box)

         Sprite      Identifies the sprite.

         Box         Gives box position and dimensions.

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

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

         See as_SetValue to set the "opaque" level of a sprite.

See also:as_Collide, as_CollideBox, as_SetValue/AS_VALUE_OPAQUE_LEVEL



============================================================================
as_Invalidate                                   Force a sprite to be redrawn

as_Invalidate marks a sprite to be redrawn. You need this function when you
have manually changed the sprite's appearance (by directly accessing the DIB
of the sprite).

Syntax:  BOOL as_Invalidate(ASPRITE Sprite)

         Sprite      Identifies the sprite.

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_UNASSIGNED.

See also:as_Animate, as_GetData/AS_DATA_SPRITE
AniSprite                                              as_LastError  ---  63

============================================================================
as_IsValid                           Checks whether a sprite handle is valid

as_IsValid verifies that the handle refers to a sprite.

Syntax:  int as_IsValid(ASPRITE Sprite)

         Sprite      The sprite handle.

Returns: TRUE if the handle is valid, FALSE if the sprite was previously
         deleted or of the handle is garbage.



============================================================================
as_IsValidBoard                       Checks whether a board handle is valid

as_IsValidBoard verifies that the handle refers to a board.

Syntax:  int as_IsValidBoard(ASBOARD Board)

         Board       The board handle.

Returns: TRUE if the handle is valid, FALSE if the board was previously
         deleted or of the handle is garbage.



============================================================================
as_LastError                                           Return the last error

This function reports the last error that occurred as a result of an Ani-
Sprite function call.

Syntax:  int as_LastError(LPVOID Object)

         Object      This can either be a sprite handle (to return the last
                     error for that sprite), a board handle (returns the
                     last error for the board) or NULL to return the last
                     global error.

Returns: The last error code of the specified object.
64  ---  as_LevelInMask                                       ITB CompuPhase

Notes:   as_LastError does not reset the last occurred error code, so it
         can be called repeatedly. In 16-bit mode the last global error code
         may be shared with other applications (DLLs are shared in 16-bit
         Microsoft Windows environments).



============================================================================
as_LevelInMask                            Check the presence of a mask level

as_LevelInMask determines if a certain mask level is present in a mask. This
information can be useful if alpha levels or luma levels must be installed
for the mask.

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

         Width,
         Height      Dimensions of the masks.

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

         Level       The alpha or luma level to search for.

Returns: TRUE if the alpha or luma level is present in the mask.

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

See also:as_CreateMask, as_SetBoardData, as_ReduceMask, as_SmoothMask,
         AS_DATA_ALPHA_LEVEL, AS_DATA_LUMA_LEVEL



============================================================================
as_Link                                                     Link two sprites

as_Link attaches a sprite to a master sprite. Whenever the position or the
origin of the master sprite changes, all linked sprites move in order to
keep the same horizontal and vertical displacements from their master's
origin.

Syntax:  BOOL as_Link(ASPRITE Sprite, ASPRITE Master)
AniSprite                                                   as_Load  ---  65

         Sprite      Identifies the sprite.

         Master      Identifies the sprite to which Sprite will be linked.
                     Set this parameter to NULL to unlink a sprite.

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_UNASSIGNED.

Notes:   Both sprites must be assigned to the same board.

See also:as_PaintBoard, as_SetPos



============================================================================
as_Load                            Load a sprite from a Windows Bitmap image

as_Load reads an image in the Microsoft Windows "Bitmap" format from
disk and creates a sprite from it. The image can be loaded either from file
or from the resources of an application or a DLL. The function supports
both uncompressed and RLE compressed bitmap images. as_Load will only read
256-colour images.

Syntax:  ASPRITE as_Load(LPCSTR Filename, COLORREF crTransColor,
                         HINSTANCE hInstance, LPCSTR ResourceType)

         Filename    The complete filename or resource name of the image.

         crTransColorThe colour that is considered to be transparent.

         hInstance   The instance handle of the application or DLL from
                     whose resources the image must be read. Set this
                     parameter to NULL when loading an image from file.

         ResourceType
                     The resource type; usually RT_BITMAP or RT_RCDATA, but
                     a user defined type may also be specified. Set this
                     parameter to NULL when loading an image from file.

Returns: A sprite handle, or NULL on failure.

Errors:  AS_ERR_LOADFILE,
         AS_ERR_MEMORY.
66  ---  as_LoadBoard                                         ITB CompuPhase

Notes:   as_Load always creates a cutout mask for the sprite. To create
         sprites with a different mask type, use as_LoadDIB to load an image
         and create the mask explicitly with as_CreateMask.

         Several resource compilers do not support RLE compressed images for
         the "RT_BITMAP" resource type. Use the "RT_RCDATA" or a custom
         resource type for storing RLE compressed images.

         The memory blocks that as_Load allocates for the sprite image
         and the cutout mask must be freed with as_FreeResource. The most
         convenient way to do so is to set DeleteDIBs to TRUE in the call to
         as_Delete.

See also:as_Create, as_Delete, as_FreeResource, as_LoadBoard,
         as_LoadDIB



============================================================================
as_LoadBoard                        Load a board from a Windows Bitmap image

as_LoadBoard reads an image in the Microsoft Windows "Bitmap" format from
disk and creates a board from it. The image can be loaded either from file
or from the resources of an application or a DLL. The function supports both
uncompressed and RLE compressed bitmap images. as_LoadBoard will only read
256-colour images.

Syntax:  ASBOARD as_LoadBoard(LPCSTR Filename, int Code,
                              HINSTANCE hInstance,
                              LPCSTR ResourceType)

         Filename    The complete filename or resource name of the image.

         Code        The properties of the board, see as_CreateBoard for
                     more information.

         hInstance   The instance handle of the application or DLL from
                     whose resources the image must be read. Set this
                     parameter to NULL when loading an image from file.

         ResourceType
                     The resource type; usually RT_BITMAP or RT_RCDATA, but
                     a user defined type may also be specified. Set this
                     parameter to NULL when loading an image from file.
AniSprite                                                as_LoadDIB  ---  67

Returns: A board handle, or NULL on failure.

Errors:  AS_ERR_LOADFILE,
         AS_ERR_MEMORY.

Notes:   Several resource compilers do not support RLE compressed images for
         the "RT_BITMAP" resource type. Use the "RT_RCDATA" or a custom
         resource type for storing RLE compressed images.

         The memory block that as_LoadBoard allocates must be freed with
         as_FreeResource. The most convenient way to do so is to set Delete-
         DIB to TRUE in the call to as_DeleteBoard.

See also:as_CreateBoard, as_DeleteBoard, as_FreeResource, as_Load,
         as_LoadDIB



============================================================================
as_LoadDIB                           Load a Windows Bitmap image or resource

as_LoadDIB reads an image in the Microsoft Windows "Bitmap" format from
disk into memory. The image can be loaded either from file or from the re-
sources of an application or a DLL. The function supports both uncompressed
and RLE compressed bitmap images. as_LoadDIB will only read 256-colour
images.

Syntax:  LPVOID as_LoadDIB(LPCSTR Filename, LPBITMAPINFO BmpInfo,
                           HINSTANCE hInstance,
                           LPCSTR ResourceType)

         Filename    The complete filename or resource name of the image.

         BmpInfo     Points to a BITMAPINFO structure (a header and a colour
                     table with 256 entries) that will contain the DIB
                     header information for the DIB pixels that the function
                     returns.

         hInstance   The instance handle of the application or DLL from
                     whose resources the image must be read. Set this
                     parameter to NULL when loading an image from file.

         ResourceType
                     The resource type; usually RT_BITMAP or RT_RCDATA, but
                     a user defined type may also be specified. Set this
                     parameter to NULL when loading an image from file.
68  ---  as_MapMaskLevel                                      ITB CompuPhase

Returns: A pointer to the DIB pixels.

Notes:   Several resource compilers do not support RLE compressed images for
         the "RT_BITMAP" resource type. Use the "RT_RCDATA" or a custom
         resource type for storing RLE compressed images.

         The memory block that as_LoadDIB allocates must be freed with
         as_FreeResource.

See also:as_FreeResource, as_Load, as_LoadBoard



============================================================================
as_MapMaskLevel                     Change a mask level to a different level

as_MapMaskLevel is superseeded by function as_MapMultiLevels. The function
as_MapMaskLevel moves a single mask level to a new position, while function
as_MapMultiLevels can move several levels in a single call.



============================================================================
as_MapMultiLevels                      Move mask levels upwards or downwards

as_MapMultiLevels moves a sequence of all mask values statring with
the value From to the value To. This is useful for fading, or for post-
processing a mask that is created with as_CreateMask.

Syntax:  BOOL as_MapMultiLevels(int Width, int Height,
                                LPVOID MaskBits, int From, int To, int Num)

         Width,
         Height      Dimensions of the mask.

         MaskBits    The mask bits in 8-bpp DIB format.

         From        The first mask value that must move to To.

         To          The new mask value to which From must be moved.

         Num         The number of consecutive mask values to move.
AniSprite                                             as_PaintBoard  ---  69

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_INVALIDVALUE.

See also:as_CreateMask, as_ReduceLevel, as_SmoothMask



============================================================================
as_Move                                                      Move the sprite

as_Move moves a sprite relative to its current position on its board.

Syntax:  BOOL as_Move(ASPRITE Sprite, int DeltaX, int DeltaY)

         Sprite      Identifies the sprite.

         DeltaX,
         DeltaY      The amount to move to the right and to the bottom.
                     These values may be negative (to move to the left or to
                     the top).

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_UNASSIGNED.

Notes:   After a call to as_Move the board must be painted if the sprite was
         visible.

         Sprites may be moved anywhere, even outside the board.

         Linked sprites move along with their master sprite.

See also:as_PaintBoard, as_SetPos



============================================================================
as_PaintBoard                                  Draw the board on the display

as_PaintBoard updates the screen, so that it represents the current state of
the board.

Syntax:  BOOL as_PaintBoard(HDC hDC, ASBOARD Board,
                            int X, int Y, BOOL PaintAll)
70  ---  as_PaintBoard                                        ITB CompuPhase

         hDC         Microsoft Windows display context. If this handle is
                     NULL, the action depends on whether or not the board is
                     attached to a "board window" (see "notes" below).

         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 have changed after the previous
                     call to as_PaintBoard. Typically, PaintAll is TRUE
                     when as_PaintBoard is called in the WM_PAINT message
                     processing; and PaintAll is FALSE outside the context
                     of a WM_PAINT message.

Returns: Returns TRUE if any part of the board was updated.

Errors:  AS_ERR_INVALIDHANDLE.

Notes:   After calling as_PaintBoard, there are no invalid parts left on the
         board.

         If the hDC parameter is NULL and a board window is attached to
         the board, as_PaintBoard automatically allocates a display context
         handle (HDC) for the board window.

         When the hDC parameter is NULL and there is no board window,
         function as_PaintBoard calculates the region of areas that must be
         updated (the region of changes), but it does not actually update
         the board or call the callback functions. You can access rectangles
         from the region with as_GetBoardData/AS_DATA_REGIONRECT.

         If you have not set a palette for the board with as_SetPalette, you
         must select and realize the palette in the hDC before calling this
         function. If you set AS_MODE_PAL_COLORS, this palette must be based
         on the colour table passed to as_CreateBoard.

         If the board is created with the AS_MODE_NODRAW style, the board
         is updated, but not painted in the display context (HDC). You can
         access the updated internal "scratch image" with as_GetBoardData.
         See also page  8.
AniSprite                                             as_PtInSprite  ---  71

         A board that has the AS_MODE_NODRAW style still needs to pass in a
         valid display context handle (HDC), since as_PaintBoard uses it to
         create the DIB section, to handle DDB callbacks, and to handle a
         few internal operations.

See also:as_Animate, as_GetBoardData/AS_DATA_REGIONRECT as_Move,
         as_ReplaceBoard, as_SetPos



============================================================================
as_PtInBoard                    Check whether a position is inside the board

This function determines if the given position is in the board.

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

         Board       Identifies the board.

         X, Y        The position to verify. Coordinates are relative to the
                     upper left corner of the board image.

Returns: TRUE if the position (x, y) is in the board and FALSE otherwise.

See also:as_PtInSprite, as_CollideBox



============================================================================
as_PtInSprite                    Check whether a pixel is part of the sprite

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. Coordinates are relative to the upper left
                     corner of the board image.

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

Errors:  AS_ERR_UNASSIGNED.
72  ---  as_ReduceMask                                        ITB CompuPhase

Notes:   as_PtInSprite does not look after the current visibility state and
         the layer of the sprite. Possible sprites on top of the sprite are
         ignored.

         See as_SetValue to set the "opaque" level of a sprite.

See also:as_SetValue/AS_VALUE_OPAQUE_LEVEL, as_SpriteAtPos



============================================================================
as_ReduceMask                               Reduce the number of mask levels

as_ReduceMask reduces the number of levels in a luma mask or an alpha mask
to the number that you specify. Many "paint" programs that support alpha
channels store a full depth (256 levels) alpha mask. AniSprite is optimized
for a reduce number of alpha levels (see the chapter "Masks" on page  9 and
the optimization tips on page  22).

Syntax:  BOOL as_ReduceMask(int Width, int Height,
                            LPVOID MaskBits, int Levels)

         Width,
         Height      Dimensions of the masks.

         MaskBits    The mask bits in 8-bpp DIB format.

         Levels      The number of intermediate levels between transparent
                     and opaque. Set Levels to zero to create a cutout mask.

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_INVALIDVALUE.

See also:as_CreateMask, as_MapMaskLevel



============================================================================
as_ReleaseTimer                               Remove a high-resolution timer

as_ReleaseTimer removes a high-resolution timer that as_SetTimer installed.

Syntax:  BOOL as_ReleaseTimer(ASBOARD Board)
AniSprite                                           as_ReplaceBoard  ---  73

         Board       The board.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_INVALIDOPERATION.

Notes:   When deleting the board, the high-resolution timer (if any) is
         removed automatically.

See also:as_SetTimer



============================================================================
as_ReplaceBoard                               Change the board image or size

This function can be used to change the board image and/or the visible
area within the board image. Both the bitmap for the (new) board image and
visible area must be supplied as parameters.

Syntax:  BOOL as_ReplaceBoard(ASBOARD Board,
                              int Width, int Height,
                              LPVOID ImageBits, LPRECT VisRect,
                              LPRECT InvalidRect)

         Board       Identifies the board.

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

         ImageBits   The new board image bits.

         VisRect     Visible part of the new board image.

         InvalidRect
                     Part of board image that changes as a consequence of
                     the animation. Set InvalidRect to NULL when the image
                     changes completely.

Returns: TRUE on success and FALSE on failure (insufficient memory).

Errors:  AS_ERR_MEMORY.
74  ---  as_ScaleDIB                                          ITB CompuPhase

Notes:   To update the board change to the screen the board must be re-
         painted with as_PaintBoard.

         This function is fast if the dimensions of the board do not change.

See also:as_CreateBoard, as_DeleteBoard, as_PaintBoard



============================================================================
as_ScaleDIB                                Resize a DIB upwards or downwards

as_ScaleDIB scales a DIB up or down, at pixel precision.

Syntax:  LPVOID as_ScaleDIB(LPBITMAPINFO SrcInfo, LPVOID SrcBits,
                            LPBITMAPINFO DstInfo, int Width,
                            int Height, BOOL DeleteSrc)

         SrcInfo     A pointer to the DIB header of the source image.

         SrcBits     A pointer to the pixel data of the source image. If
                     this parameter is NULL, the function assumes that
                     the pixel data follows the DIB header (in the SrcInfo
                     parameter) in a single memory block.

         DstInfo     A pointer to the DIB header of the resized image. This
                     header is filled by as_ScaleDIB to reflect the new
                     size.

         Width,
         Height      The size of the new image.

         DeleteSrc   If TRUE, the function deletes the source image upon
                     successful completion. The memory block for the source
                     image must have been allocated by an AniSprite function
                     for this to work correctly.

Returns: A pointer to the DIB pixels of the scaled image.

Notes:

         The memory block allocated by as_ScaleDIB must be freed with a call
         to as_FreeResource.
AniSprite                                           as_SetBoardData  ---  75

See also:as_ContertImage, as_CropImage, as_FreeResource


============================================================================
as_SetBoardData                                               Set board data

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

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

         Board       Identifies the board.

         Code        Indicates which board pointer is to be modified. The
                     Code can be any of the following values:

                     * AS_DATA_ALPHA_LEVEL
                       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
                       kBytes. In 16-bit mode the value pointer must have
                       zero offset. This can be accomplished in two possible
                       ways: by using as_CreateAlphaLevel, when a new level
                       is calculated, and by as_AllocResource, when the
                       level is loaded from disk.

                       Use as_CreateAlphaLevel to calculate an alpha level.

                     * AS_DATA_LUMA_LEVEL
                       Typically, luma levels are installed in such a way,
                       that they enable luma masks to gradually increase or
                       decrease the brightness of the background image.

                       Use as_CreateLumaLevel to calculate a luma level.

                     * AS_DATA_USERDATA
                       Set "user data". The pointer can be used for any
                       purpose. The Index parameter should be zero.
76  ---  as_SetData                                           ITB CompuPhase

         Index       Index indicates which alpha or luma level is to be
                     modified.

         Value       The data pointer that must be set. The object that
                     Value points to must stay valid while the board exists.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_INVALIDCODE,
         AS_ERR_INVALIDINDEX,
         AS_ERR_INVALIDPOINTER (16-bit only),
         AS_ERR_UNSUPPORTED.

Notes:   You should not delete the memory for the alpha and luma levels as
         long as the board uses them.

See also:as_AllocResource, as_CreateAlphaLevel, as_CreateBoard,
         as_CreateLumaLevel, as_GetBoardData as_SetBoardValue



============================================================================
as_SetData                                                   Set sprite data

as_SetData installs pointers to callback functions and other sprite related
data.

Syntax:  BOOL as_SetData(ASPRITE Sprite, int Code, int Index,
                         LPVOID Value)

         Sprite      Identifies the sprite.

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

                     * AS_DATA_CALLBACK
                       Callback function pointer to install. Initially a
                       sprite has no callback functions. The Index parameter
                       must be one of the following:
                       o AS_EVENT_COLLIDE: Collision between sprites.
                       o AS_EVENT_PAINT_DDB: paint sprite, DDB format.
                       o AS_EVENT_PAINT_DIB: paint sprite, DIB format.
                       o AS_EVENT_TIMER: Periodic timer event.
AniSprite                                              as_SetOrigin  ---  77

                       o AS_EVENT_MOUSE: Mouse event (click, move, leave).

                       See page  18 for more information on callback func-
                       tions.

                     * AS_DATA_USERDATA
                       Set "user data". The pointer can be used for any
                       purpose. The Index parameter should be zero.

         Index       Depends on the Code parameter.

         Value       The data pointer that must be set.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_INVALIDCODE.

Notes:   If you need to maintain extra information for each sprite, a
         convenient method is to store that information in a structure and
         to set the pointer to that structure as user data.

See also:as_GetData, as_SetValue


============================================================================
as_SetOrigin                                    Set the origin of the sprite

as_SetOrigin specifies the origin of the sprite relative to the upper left
corner of the sprite's image.

Syntax:  BOOL as_SetOrigin(ASPRITE Sprite, int Xorg, int Yorg)

         Sprite      Identifies the sprite.

         Xorg, Yorg  The position of the origin of the sprite.

Returns: TRUE on success, FALSE on failure.

Notes:   The default origin of a sprite is the upper left corner; that is,
         the origin is at (0,0) by default.

         Changing the origin of a sprite causes all linked sprites to move,
         because the positions of linked sprites are relative to the origin
         of their master.

         The origin of a sprite may be outside the sprite itself.
78  ---  as_SetPalette                                        ITB CompuPhase

See also:as_GetValue, as_Move, as_SetPos


============================================================================
as_SetPalette                                        Set the board's palette

as_SetPalette creates and sets a palette for the board.

Syntax:  BOOL as_SetPalette(ASBOARD Board, LPRGBQUAD Palette,
                            BOOL IdentPalette)

         Board       The board handle.

         Palette     A pointer to 256 RGBQUAD structures with the informa-
                     tion from the bitmap colour table.

         IdentPalette
                     If TRUE, as_SetPalette creates an identity palette. See
                     notes below.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_MEMORY.

Notes:   Setting a palette is optional, but it has the following advantages:
         * You do not have to create and handle a palette yourself. Function
           as_PaintBoard selects the palette, and as_Delete destroys the
           palette. The Microsoft Windows 'messages WM_PALETTECHANGED and
           WM_QUERYNEWPALETTE are handled by as_ForwardMessage.
         * as_SetPalette can create an identity palette, which results
           in faster BitBlts from memory to the screen (and hence, faster
           overall animation).

         If you create an identity palette, the first 10 and the last 10
         colours in the table that Palette points to must be the 20 static
         colours that Microsoft Windows reserves. Many paint and rendering
         programs support the inclusion of the Windows static colours.

         It is advised that you use the colour table of the board for the
         palette. For example:

             Board = as_CreateBoard(BitsInfo, ImageBits, NULL, 0L);
             as_SetPalette(Board, BitsInfo->bmiColors, TRUE);
AniSprite                                               as_SetTimer  ---  79

         For fastest animation, use "palette colour" mode in combi-
         nation with an identity palette (see as_CreateBoard for the
         AS_MODE_PAL_COLORS flag).

See also:as_CreateBoard, as_GetBoardHandle



============================================================================
as_SetPos                                       Set the position of a sprite

as_SetPos gives a sprite a new position on its board.

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

         Sprite      Identifies the sprite.

         X, Y        The position at which the origin of the sprite is to be
                     placed, relative to the upper left corner of the board
                     image.

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_UNASSIGNED.

Notes:   After a call to as_SetPos the board must be painted if the sprite
         was visible.

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

         Sprites may be moved anywhere, even outside the board.

         See as_SetOrigin to change the position of the origin in the
         sprite.

         Linked sprites move along with their master sprite.

See also:as_Animate, as_GetPos, as_Move, as_PaintBoard



============================================================================
as_SetTimer                               Initialize a high-resolution timer

as_SetTimer sets a high-resolution timer for the board.
80  ---  as_SetTimer                                          ITB CompuPhase

Syntax:  BOOL as_SetTimer(ASBOARD Board, HWND hwnd, WORD Interval)

         Board       The board.

         hwnd        The handle of the window that will receive the AS_TIMER
                     message.

         Interval    The requested timer interval, in milliseconds.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_NORESOURCES,
         AS_ERR_UNSUPPORTED.

Notes:   Function as_SetTimer improves on the standard SetTimer function of
         Microsoft Windows in two ways:
         * The timer has a resolution of 1 millisecond. The standard Win-
           dows 'timer has a resolution of 55 ms, which is too coarse for
           most animations. (Note that the requested timer interval should
           be a multiple of the timer resolution to avoid irregularities in
           the interval.)
         * Windows generates the WM_TIMER message when the message queue
           is empty and no other event is pending. In other words, the
           WM_USER message can easily be delayed, because nearly every
           other operation has a higher priority. as_SetTimer generates an
           AS_TIMER message that has the same priority as other messages.

         The message AS_TIMER is defined as (WM_USER + 89).

         You can set only one timer per board. Function as_ReleaseTimer
         removes with the timer. The timer is also removed when the board is
         deleted.

         According to the documentation of Microsoft Windows, the Multimedia
         timer system may give you a timer interval that is higher or lower
         than the one you requested (and the precise upper and lower limits
         are said to be implementation defined). You can query the precise
         timer interval that as_SetTimer has set up with as_GetBoardValue.

See also:as_GetBoardValue/AS_VALUE_TIMERRES, as_ReleaseTimer
AniSprite                                                   as_Show  ---  81

============================================================================
as_SetValue                                           Set a sprite parameter

as_SetValue sets sprite related values.

Syntax:  int as_SetValue(ASPRITE Sprite, int Code, int Value)

         Sprite      Identifies the sprite.

         Code        Indicates which sprite value must be set. The Code
                     parameter can be any of the following:

                     * AS_VALUE_ID
                       The sprite id is any value that you choose. This
                       value is not used by AniSprite itself.

                     * AS_VALUE_MASKCODE
                       The mask type of the sprite. You can change the mask
                       type to any of the following values:
                       o AS_MASK_ALPHA
                       o AS_MASK_CUTOUT
                       o AS_MASK_LUMA
                       o AS_MASK_NONE

                     * AS_VALUE_OPAQUE_LEVEL
                       This is the level below which a pixel in the mask
                       is considered "opaque". The default value is 254,
                       meaning that all mask levels of 254 and below are
                       opaque.

         Value       The new value for the item in Code.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_INVALIDCODE.

See also:as_GetValue, as_SetBoardValue, as_SetData



============================================================================
as_Show                                                Show or hide a sprite

as_Show shows or hides the sprite. A "visible" sprite may be obscured by
other sprites on top of it.
82  ---  as_SmoothMask                                        ITB CompuPhase

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: TRUE if the visibility state of the sprite changed.

Errors:  AS_ERR_UNASSIGNED.

Notes:   Visibility changes must be updated with as_PaintBoard; as_Show
         itself does not change the screen contents.

         If the "show/hide" operation is set to be incremental, the
         number of "show" operations must match the number of "hide"
         operations to return to the original state. Otherwise the sprite
         stays "hidden". For example, if a sprite is hidden twice, you
         must also perform the "show" operation twice; the sprite remains
         hidden after a single "show" operation.

         To set "incremental show/hide", use a mode flag when creating
         the board. The default setting for the "show/hide" operations is
         "absolute", where a "show" operation always makes the sprite
         visible regardless of the number of preceding "hide" operations.

See also:as_PaintBoard, as_GetValue/AS_VALUE_VISIBLE



============================================================================
as_SmoothMask                              Smooth the edges of a cutout mask

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. The resulting alpha mask enables
AniSprite to blit the sprite anti-aliased onto the board.

Syntax:  BOOL as_SmoothMask(int Width, int Height, LPVOID MaskBits, int
                            Feather, int Levels)

         Width,
         Height      Dimensions of the masks.
AniSprite                                            as_SpriteAtPos  ---  83

         MaskBits    The mask bits in 8-bpp DIB format.

         Feather     The width (in pixels) of the semi-transparent edge.

         Levels      The number of intermediate levels between transparent
                     and opaque.

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_INVALIDVALUE.

Notes:   There are always at least two levels: opaque and transparent (mask
         values 0 and 255 respectively). The alpha and luma blending tables
         are predefined for these two levels. In this function, you pass the
         number of additional levels that you wish to keep in the mask. When
         Levels is 3, the resulting mask has 5 levels: opaque, transparent
         and 3 translucent levels.

         The feather width may be greater or smaller than the number of
         (intermediate) levels.

See also:as_CreateMask, as_ReduceMask



============================================================================
as_SpriteAtPos                           Check which sprite is at a location

as_SpriteAtPos returns the topmost visible sprite at the given position.

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

         Board       Identifies the board.

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

         Sprite      The sprite at which to start searching. If this pa-
                     rameter is NULL, the function returns the highest
                     sprite at the given position, otherwise it returns the
                     next-highest sprite at the position that is below the
                     specified sprite.
84  ---  as_SpriteAtPos                                       ITB CompuPhase

Returns: The top most visible sprite that is opaque at the given position
         and that is below the sprite denoted by the argument Sprite if
         Sprite is not NULL.

         If there is no sprite (or no sprite below Sprite) at this position,
         the return value is NULL.

Errors:  AS_ERR_NONE.

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

         By repeatedly calling this function with the same coordinate
         pair and passing the returned sprite handle at the next call
         to as_SpriteAtPos, you can walk through all sprites at a given
         location.

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

See also:as_PtInSprite
AniSprite                                               Error codes  ---  85

                                Error codes                      Appendix A

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

AS_ERR_NONE
          No error.

AS_ERR_ASSIGNED
          An attempt to delete a sprite that is still assigned to a board
          layer. When a sprite is deleted, it may not be part of an ani-
          mation to prevent inconsistent board situations.

AS_ERR_BOARDMISMATCH
          Occurs when a sprite is re-assigned to a board layer, while it's
          already assigned to a layer of another board. Re-assigments are
          only allowed within the same board.

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

AS_ERR_INVALIDCRDS
          The coordinates are invalid.

AS_ERR_INVALIDHANDLE
          A passed-in Windows handle (usually a hDC) was NULL or otherwise
          invalid.

AS_ERR_INVALIDINDEX
          Any of the value (or data) setting/retrieval functions, was called
          with an invalid code index. See the function documentation for
          valid values.

AS_ERR_INVALIDOPERATION
          A general "invalid function call'; e.g. a call to as_ReleaseTimer
          without having called as_SetTimer first.

AS_ERR_INVALIDPOINTER
          This error can only occur in 16-bit mode. Since AniSprite uses
          far pointers to access alpha level data and since one alpha level
          block is exactly 64 kBytes, the pointer offset of an alpha level
          must be zero. If it's not this error occurs.
86  ---  Error codes                                          ITB CompuPhase

AS_ERR_INVALIDVALUE
          Any of the value setting/retrieval functions, was called with an
          invalid value.

AS_ERR_LOADFILE
          Error loading file or image resource; usually this means that the
          file or resource is not found.

AS_ERR_NORESOURCES
          A general purpose error that indicates that Windows could not
          allocate some resource,

AS_ERR_NOTEMPTY
          This error is the opposite of AS_ERR_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.

AS_ERR_OPAQUE
          AniSprite can make a mask from an image using transparent colours.
          If none of the given transparent palette colours is in the image
          palette, AniSprite generates this error.

AS_ERR_MEMORY
          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_ERR_UNASSIGNED
          Most sprite operations can only proceed if the sprite is assigned
          to a board layer. If it isn't AniSprite, generates an "unas-
          signed" error.

AS_ERR_UNSUPPORTED
          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.

          This error also occurs, when board levels are set or retrieved for
          unsupported board modes.
AniSprite                                               Error codes  ---  87

AS_ERR_WRONGFORMAT
          AniSprite reports this error if as_CreateBoard or as_CreateMask
          has a bitmap image as parameter, that isn't a 256 colour DIB.
          Other functions that have image parameters assume 256 colour
          images too.

          When this error occurs, you can convert the image to the right 8-
          bpp DIB format with as_ConvertImage. It converts images with up to
          256 colours. HiColor and true-colour images can not be converted.
88  ---  Using AniSprite with EGI                             ITB CompuPhase

                          Using AniSprite with EGI                Appendix B

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

EGI is a frame based animation engine, developed by CompuPhase. The ani-
mation files used by EGI are precompiled movies, just like Microsoft's Video
for Windows or Autodesk Animator.

Just like AniSprite, EGI provides a low level interface, by means of which
you can access the raw data. And just like AniSprite, the interface is based
on common Microsoft Windows 'formats, like the Device Independent Bitmap
(DIB). This makes it straightforward to combine AniSprite and EGI.

The advantages of combining a frame animation toolkit and a sprite animation
toolkit are:

* Low memory consumption. EGI uses an inter-frame compression scheme. This
  is more compact than the common approach to have all appearances of a
  sprite in one large bitmap.

* Better tools for internal animation. There are several paint programs
  that can save a file directly in a format that EGI can use (the FLIC
  format). In addition, these tools make it easier to align the "frames"
  of a sprite by layering the frames on a digital lightbox. One such tool
  is Cosmigo's "Pro Motion" (see appendix D for the Internet address of
  Cosmigo).

* Faster operation by pre-compiling information instead of calculating it
  run time. EGI can store the masks in the format that AniSprite requires.


The details

To combine AniSprite and EGI, first create the board as usual. Then open the
frame animation file (a FLIC file). I assume that you know how to use EGI as
a separate product; if not, look up the EGI manual. The handle to the frame
(the LPFLIC type) animation can be conveniently stored in the "user data"
of the sprite; see the last line in figure 9. You have to create the sprite
first, however. And to do that, you must ask EGI to decode the first image
of the frame animation.
AniSprite                                  Using AniSprite with EGI  ---  89

----------------------------------------------------------------------------
      Flic = FlicOpen("my_anim.flc");
      FlicNextFrame(Flic);              /* get first image */

      ImageBits = FlicGetData(Flic, FLIC_DATA_BITMAP);
      MaskBits = FlicGetData(Flic, FLIC_DATA_MASK);
      width = FlicGetParam(Flic, FLIC_PARAM_WIDTH);
      height = FlicGetParam(Flic, FLIC_PARAM_HEIGHT);

      Sprite = as_Create(width, height, MaskBits,
                         AS_MASK_CUTOUT, ImageBits, TRUE);

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

      as_SetData(Sprite, AS_DATA_USERDATA, Flic);
----------------------------------------------------------------------------
Figure 9: Creating a "frame animated" sprite

Every time you want to update the sprite's appearance (for example, at every
timer tick), you use as_Animate to load the new frame. For example:

----------------------------------------------------------------------------
  Flic = as_GetData(Sprite, AS_DATA_USERDATA);
  FlicNextFrame(Flic);

  as_Animate(Sprite, width, height,
             FlicGetData(Flic, FLIC_DATA_MASK), AS_MASK_CUTOUT,
             FlicGetData(Flic, FLIC_DATA_BITMAP), TRUE,
             NULL);
----------------------------------------------------------------------------
Figure 10: Setting a new image

And when finished, you delete the sprite without deleting the images for
the sprite and the mask. AniSprite does not own the memory of these bitmaps,
so it should not attempt to delete them. Instead, you must close the frame
animation file:
90  ---  Using AniSprite with EGI                             ITB CompuPhase

----------------------------------------------------------------------------
  Flic = as_GetData(Sprite, AS_DATA_USERDATA);
  FlicClose(Flic);
  as_Delete(Sprite, FALSE);
----------------------------------------------------------------------------
Figure 11: Closing down, cleaning up, ...

This is the interface between AniSprite and EGI in a nutshell. Here, we have
simply used EGI as an "image archive". More advanced techniques are to
have EGI provide the timing for the internal animation, with FlicPlay, and
to react on the events that EGI sends to the application.
AniSprite                                   Using the "trace" DLLs  ---  91

                          Using the "trace" DLLs                Appendix C

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

NOTE: the trace DLLs are included in the retail version only.

The AniSprite product comes with two "trace" DLLs, for 16-bit and 32-bit
applications, that replace the retail DLLs. The trace DLLs run more slowly
than the retail DLLs, because they test the parameters to functions more
extensively.


Installation

You will find the trace DLLs in the "BIN" subdirectory of the main Ani-
Sprite installation directory. Their names are:
AS16T.DLL   trace DLL for 16-bit applications
AS32T.DLL   trace DLL for 32-bit applications

To use the trace DLL with a program, rather than the retail DLL, simply copy
the trace DLL to the same directory where the program resides and rename
it to AS16.DLL or AS32.DLL. When you start the program, you should see a
message box notifying the use of the trace DLL at the first board that the
program creates.


Intercepting error output

The trace DLLs use the Windows 'function OutputDebugString to send error
messages to an application debugger or to a kernel debugger. Some debuggers
require that you run the "debug" kernel of Microsoft Windows to this end.
Next to debuggers, there exist programs that specifically log the messages
issued by OutputDebugString, and these may be more convenient because they
usually do not require the Microsoft Windows debug kernel. For example:

DBMON
  Comes as a programming example with the Microsoft Windows SDK and the
  Microsoft Visual C/C++ compiler (as source code only). An older 16-bit
  version shipped with the Windows 3.1 SDK.

DebugView
  By System Internals, see "http://www.sysinternals.com". DebugView runs
  on Windows 95, Windows 98 and Windows NT.
92  ---  Getting more information                             ITB CompuPhase

                          Getting more information                Appendix D

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

For additional information on animation and Microsoft Windows programming,
see our homepage at:



                          http://www.compuphase.com

Relevant topics are:
* The frame animation engine EGI, a good companion to AniSprite, plus a demo
  of the combined features of EGI and AniSprite.
* Application notes on advanced or non-standard uses of AniSprite, such as
  using transparent boards and synchronizing AniSprite animations with MIDI
  audio.
* Details on Windows 'Palette Manager: how to create an identity palette,
  how to prevent Windows from shuffling your carefully crafted palette, why
  identity palettes are faster, ... Highly recommended.
* Background information on the colour matching formulae that AniSprite uses
  to calculate alpha and luma blending tables.
* How the feathering algorithm works that as_SmoothMask uses.
* And an assortment of tips and resources for computer animation.

Upon request, we can also send you this information by e-mail (in HTML
format) or by fax. Our address is on the inside title page.

Pro Motion is available on the following URL address:



                      http://www.cosmigo.com/promotion
AniSprite                                                     Index  ---  93

                                    Index

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


Action, 4, 8                             Bounding box, 30, 33, 53
  buffered, 8                            bpp, 36, 37, 49
Alpha                                    Buffered actions, 8
  blending, 4, 39, 40
  level, 17, 23, 39, 75, 82
  mask, 10, 82                           C language, 11
Animation                                Callback functions, 18, 56, 76
  external, 2                              collision, 21
  internal, 2, 88                          DDB, 19, 70
Anti-aliasing, 82                          DIB, 20
as_AllocResource, 13                       mouse, 22
as_ForwardMessage, 21, 22                  timer, 21
as_FreeResource, 13                      Cel animation, See Frame animation
as_Load, 65                              Chroma key, 4
as_LoadBoard, 66                         Collision detection, 5, 21, 34--36
as_LoadDIB, 67                           Colour models, 92
AS_MODE_NODRAW, 70                       Coordinates, 8
as_ScaleDIB, 74                          Cutout mask, 5, 9, 23
as_Show, 81
AS_TIMER, 21, 80
Autodesk Animator, 88                    DDB, 19, 60
                                           board, 32
                                           callback, 19, 70
Binary mask, 9, 17                         format, 5
BITMAPINFO, 20, 32, 37                   DIB, 19, 23, 31, 36, 88
BMP files, 65--67                          callback, 20
Board, 4, 8                                format, 5, 9
  coordinates, 8                         DIB section, 41, 54, 70
  image, 8                               Differential encoding, 30
  layer, 14                              Display Context, 19, 70
  masked, 42
  Window, 43, 48
Borland                                  EGI, 3, 88
  C++, 11, 28                            Examples, 27
94  ---  Index                                                ITB CompuPhase


Fade effect, 15
Flare effect, 6, 44
Forwarded messages, 50                   Messages
Frame animation, 2, 88                     forwarded, 50
                                         Metric (colour), 92
                                         Microsoft
GDI, 19                                    Visual C/C++, 11, 28
Grab                                     Mouse
  palette, 61                              callback, 22
  screen, 60

                                         Opaque level, 6, 21, 35, 36, 59, 72,
HBITMAP, 54                                81
HDC, 70                                  Origin, 6, 58, 60, 77, 79
HiColor, 37
Hidden sprite, 22, 37
HPALETTE, 54                             Palette, 6, 10
                                           adapt, 36
                                           handle, 54
Identity palette, 23                       identity, 5, 23, 78
Incremental show/hide, 41, 82              index, 57, 58
Invalid rectangle, 30                      Manager, 92
Invisible sprite, See Hidden sprite        message, 14
                                           mode, 42, 55
                                         Palette grab, 61
Layer, 5, 14, 21                         Pro Motion, 88
Linked sprites, 6, 64, 69, 77, 79        Programming examples, 27
Luma
  blending, 6, 40, 44
  level, 23, 44, 75                      RGBQUAD, 37, 78
  mask, 10                               RLE compression, 65--67
                                           limitations, 66--68

Mask
  alpha, 10, 82
  binary, 9, 17                          Scratch image, 8, 20, 23, 70
  capabilities, 13                       Screen grab, 60
  cutout, 5, 9, 23, 82                   SetTimer, 80
  luma, 10                               Shadow effect, 6, 44
Masked board, 42                         Slot, 6
Memory management, 13                    Spotlight effect, See Flare effect
AniSprite                                                     Index  ---  95


Sprite                                   True-Color, 37
  action, 4, 8
  animation, 2
  collision, 5, 34--36                   User data, 53, 57, 75, 77
  hidden, 22, 37
  linked, 6, 64, 69, 77, 79
  origin, 6, 58, 60, 77, 79              Video for Windows, 88
StretchDIBits, 41

                                         Watcom C/C++, 11, 28
Timer, 80                                WM_MOUSELEAVE, 22
  callback, 21                           WM_PAINT, 14, 70
Trace DLL, 91                            WM_PALETTECHANGED, 14
Translucent, 6, 7                        WM_QUERYNEWPALETTE, 14
