
ii                                                            ITB CompuPhase

                              License Agreement


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

This manual and the software programs consisting of all the files included
on the accompanying magnetic disk labeled "AniSprite" and hereafter
collectively referred to as "the product", are licensed to you under the
following conditions:

                                  YOU MAY:

* Make copies of the original product diskette for back-up purposes.

* Use the development files from the product on your development computer.
  This is a single user license: only one person may use the development
  files at any time.

* Distribute the files "AS16.DLL" and "AS32.DLL" as part of a published
  computer application program, provided that this published computer
  program does not directly compete with the product.

* Modify the product provided that you have obtained a source code license.

                                YOU MAY NOT:

* Distribute (modified or unmodified) copies of any part of the product
  other than the files "AS16.DLL" and "AS32.DLL", except when you have a
  separate and specific license to do so.

* Distribute (modified or unmodified) copies of the files "AS16.DLL" or
  "AS32.DLL" independently of a published computer program.

* Distribute copies of this manual or any part thereof.

* Remove or conceal the copyright of the product. The product is and remains
  the property of ITB CompuPhase.

                              LIMITED WARRANTY:

ITB CompuPhase cannot be held liable for any damage or loss of profits that
results from the use of the product (or part thereof), or from the inability
to use it.

ITB CompuPhase cannot provide support for modified versions of the product.
AniSprite


****************************************************************************
----------------------------------------------------------------------------
                                                                 Version 2.0



----------------------------------------------------------------------------
****************************************************************************
                                                              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" is a trademark of ITB CompuPhase.



Copyright (c) 1996--1998, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Using AniSprite  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
    General operation  . . . . . . . . . . . . . . . . . . . . . . . . . . 6
    Masks  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
    Compiling and linking  . . . . . . . . . . . . . . . . . . . . . . . . 9
    Set up an animation  . . . . . . . . . . . . . . . . . . . . . . . . . 9
    Clean up an animation  . . . . . . . . . . . . . . . . . . . . . . .  11
    Fade an image  . . . . . . . . . . . . . . . . . . . . . . . . . . .  11
    Callback functions . . . . . . . . . . . . . . . . . . . . . . . . .  14
    Tips for optimizing AniSprite  . . . . . . . . . . . . . . . . . . .  18
    A programming example  . . . . . . . . . . . . . . . . . . . . . . .  19
Function reference . . . . . . . . . . . . . . . . . . . . . . . . . . .  25
Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  73
    A: Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . .  74
    B: Using AniSprite with EGI  . . . . . . . . . . . . . . . . . . . .  77
    C: Getting more information  . . . . . . . . . . . . . . . . . . . .  80
Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  81
vi                                                            ITB CompuPhase



AniSprite                                               Introduction  ---  1

                                Introduction


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

AniSprite is a multiple layer sprite animation library for Microsoft Win-
dows 3.1, Windows 95 and Windows NT. It is aimed at games and multi-media
programmers.


Features

AniSprite has all the standard features that one expects in a sprite lib-
rary, 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 collision detection
* high performance (critical routines in optimized assembler)
* 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.
* full source is available
* Windows DLL interface, libraries/definition files for C/C++
* integrates with EGI (frame animation engine), see appendix B
2  ---  Animation                                             ITB CompuPhase

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.

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.
AniSprite                                                   Glossary  ---  3

                                  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.

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.

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

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

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

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.

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 destin-
                    ation 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.
AniSprite                                                   Glossary  ---  5

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

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.

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

           [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.
8  ---  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                                        Set up an animation  ---  9

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. 32-
Bit programs should use the specific AS32x.LIB for their compiler. The
distribution disk comes with three 32-bit libraries, for the C compilers
of Microsoft, Borland and Watcom, named AS32M.LIB, AS32B.LIB and AS32W.LIB
respectively.



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.
10  ---  Set up an animation                                  ITB CompuPhase

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.

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).
AniSprite                                             Fade an image  ---  11

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

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
12  ---  Fade an image                                        ITB CompuPhase

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.

   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(lpPal, 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.
AniSprite                                             Fade an image  ---  13

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

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_MapMaskLevel to adjust 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.
14  ---  Callback functions                                   ITB CompuPhase

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.



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 calback 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 calback 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
AniSprite                                        Callback functions  ---  15

                     * AS_EVENT_PAINT_DIB
                     * AS_EVENT_PAINT_DDB
                     * AS_EVENT_TIMER

         Value       Extra event information, depends on the event.

         Data        Extra event information, depends on the event.

Returns: Depends on the event.

The name asCallBack is a placeholder for a function name in you 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.
16  ---  Callback functions                                   ITB CompuPhase

         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.
                     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 prepar-
ation before they are called and are consequently fast. Windows GDI cannot
be used for graphical operations.

Syntax:  void 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. Eventually this sprite may even not be
                                 visible at all. (See also page  6.)
                     X, Y        Position of the sprite in the scratch
                                 image. This position refers the the lower
                                 left corner of the sprite.
                     Width,
AniSprite                                        Callback functions  ---  17

                     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,
                     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:  void 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  5.

Both sprites receive the event (if both have installed the collision call-
back) and each receives a handle of the other.
18  ---  Tips for optimizing AniSprite                        ITB CompuPhase

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

         Sprite      The sprite handle.

         Event       Always AS_EVENT_COLLIDE.

         Value       Always zero.

         Data        The handle of the sprite that this sprite touches.

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.

  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.
AniSprite                                     A programming example  ---  19

  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.

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

#define BOARD_WIDTH     640
#define BOARD_HEIGHT    480
#define ID_TIMER        1



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");
20  ---  A programming example                                ITB CompuPhase

  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, NULL, NULL)) {
    TranslateMessage(&msg);
    DispatchMessage(&msg);
  } /* while */

  return msg.wParam;
}

static LPVOID LoadBitmapBits(LPSTR FileName, LPBITMAPINFO bi)
{
  LPVOID lpBits;
  int linesz, file;
  long bitmapsz;

  /* WARNING: this routine can only load 256 colour .BMP files */
  if ((file = _lopen(FileName, OF_READ | OF_SHARE_DENY_WRITE)) >= 0) {
    _llseek(file, sizeof(BITMAPFILEHEADER), SEEK_SET);
    _lread(file, &bi->bmiHeader, sizeof(BITMAPINFOHEADER));
    _lread(file, bi->bmiColors, 256 * sizeof(RGBQUAD));
    linesz = (int) (((bi->bmiHeader.biWidth * 8 + 31) & ~31u) >> 3u);
    bitmapsz = bi->bmiHeader.biHeight * linesz;

    if ((lpBits = as_AllocResource(bitmapsz)) != NULL)
        _hread(file, lpBits, bitmapsz);
    _lclose(file);
    return lpBits;
  } /* if */
AniSprite                                     A programming example  ---  21

  return NULL;
}

LRESULT CALLBACK AnimWinFunc(HWND hwnd, unsigned message,
                             WPARAM wParam, LPARAM lParam)
{
static COLORREF crTransColor[] = {PALETTERGB(0xff, 0x00, 0xff)};  /* magenta
*/
static ASBOARD Board;
static ASPRITE Sprite;
static int stepx, stepy;
  LPBITMAPINFO lpBitsInfo;
  LPVOID lpBits, lpMask;
  PAINTSTRUCT ps;
  HDC hdc;
  int x, y, width, height;

  switch (message) {
  case WM_CREATE:
    /* lpBitsInfo is allocated temporarily */
    lpBitsInfo = as_AllocResource(sizeof(BITMAPINFO) + 256 * sizeof(RGBQUAD));

    /* create the board (with an identity palette) */
    lpBits = LoadBitmapBits("chess.bmp", lpBitsInfo);
    Board = as_CreateBoard(lpBitsInfo, lpBits, NULL, AS_MODE_PAL_COLORS);
    as_SetPalette(Board, lpBitsInfo->bmiColors, TRUE);

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

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

    /* clean up */
    as_FreeResource(lpBitsInfo);

    /* Create a timer to move the sprite, set initial direction */
22  ---  A programming example                                ITB CompuPhase

    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;

  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);
AniSprite                                     A programming example  ---  23

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

* LoadBitmapBits is a simple (and limited) function that loads a .BMP file
  into an in-memory DIB.
24  ---  A programming example                                ITB CompuPhase

* AnimWinFunc sets up the animation board in the WM_CREATE handling code,
  according to the steps starting at page page  9. 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  11.

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.
AniSprite                                          as_AllocResource  ---  25

                             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.
26  ---  as_Animate                                           ITB CompuPhase

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 lpMask, int MaskCode,
                         LPVOID lpImage, BOOL ImageMasked,
                         LPRECT lpBoundingBox)

         Sprite      Identifies the sprite.

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

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

         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
AniSprite                                                as_Animate  ---  27

         lpImage     The image bits in 8-bpp DIB format.

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

                     When the supplied mask is a cutout mask and the image
                     has been masked out, AniSprite can speed up the in-
                     memory image blitting.

         lpBoundingBox
                     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.
28  ---  as_Assign                                            ITB CompuPhase

============================================================================
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 lpBitsInfo,
                             LPVOID lpImage,
                             int srcX, int srcY)
AniSprite                                        as_BoardFromBitmap  ---  29

         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.

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

         lpBits      Pointer to the image bits 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 lp-
                                    Palette,
                                    int NumColors, int Code)

         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.

         lpPalette   The colour table that the board should use (see notes).
30  ---  as_BoundingBox                                       ITB CompuPhase

         NumColors   The number of entries in the colour table that lp-
                     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_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.

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

         Width,
         Height      The dimensions of the DIB.

         lpImage     A pointer to the source picture.
AniSprite                                                as_Collide  ---  31

         Level       The byte value in the source picture that is considered
                     to be transparent. If lpImage points to the DIB of a
                     mask of a sprite, Level is typically 255. If lpImage
                     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.

         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.
32  ---  as_CollideBox                                        ITB CompuPhase

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

         Sprite      Identifies the sprite.

         lpBox       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



============================================================================
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.
AniSprite                                           as_ConvertImage  ---  33

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.

Syntax:  LPVOID as_ConvertImage(LPBITMAPINFO lpSrcInfo,
                                LPVOID lpSrcBits,
                                LPBITMAPINFO lpDstInfo,
                                LPRGBQUAD lpPal,
                                BOOL DeleteSrc)

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

         lpSrcBits   Pointer to the source image bits. The source image may
                     be in 1-bpp, 4-bpp and 8-bpp format.

         lpDstInfo   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 lpSrcInfo.

         lpPal       Pointer to an array with 256 RGBQUAD structures de-
                     scribing the palette colours to adjust the image to.
34  ---  as_Create                                            ITB CompuPhase

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

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 HiColor and true-colour images.

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

See also:as_FreeResource



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

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

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

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

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

         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

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

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_CreateAlphaLevel                    Create an alpha blending lookup table

This function creates an alpha level, that can be installed in a board that
supports alpha blending.
36  ---  as_CreateBitmapInfoHeader                            ITB CompuPhase

Syntax:  LPVOID as_CreateAlphaLevel(LPRGBQUAD lpPal,
                                    WORD InterFactor)

         lpPal       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, lpPal 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 lpPal
         set to NULL. This is especially useful in 16-bit mode, where the
         alpha level pointer must have a zero offset (see as_SetBoardData).

         This memory resource must be deleted with as_FreeResource.

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 lpBitsInfo, int Width,
                                        int Height, LPRGBQUAD lpPal,
                                        int Colors)
AniSprite                                            as_CreateBoard  ---  37

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

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

         Colors      The number of entries in lpPal.

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.

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 lpBitsInfo,
                                LPVOID lpBits,
                                LPRECT lpVisRect, int Code)

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

         lpBits      Pointer to the image bits in 8-bpp DIB format. If this
                     parameter is NULL, the function creates a black board.
38  ---  as_CreateBoard                                       ITB CompuPhase

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

         Code        Code describes the board capabilities. These capabilit-
                     ies 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 slightly faster than the
                       GDI function StretchDIBits. DIB sections are avail-
                       able 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_LUMA
                       Prepare the board for luma blending support.

                     * AS_MODE_MASKED
                       Create a masked board. A masked board may not con-
                       tain an image (so lpBits 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.
AniSprite                                        as_CreateLumaLevel  ---  39

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

         A masked board conmtains 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_CreateLumaLevel,
         as_DeleteBoard, as_GrabImage, as_SetPalette



============================================================================
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 lpPal,
                                   COLORREF crColor,
                                   WORD InterFactor)

         lpPal       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, lpPal must be
                     set to NULL. In that case the parameters crColor and
                     Interfactor are ignored. An empty brightness level is
                     not initialized.
40  ---  as_CreateMask                                        ITB CompuPhase

         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 lpPal and the blend color crColor. An
                     InterFactor of 0 means leaves every colour in lpPal
                     unaltered and 256 sets each entry in lpPal 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.

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 lpBitsInfo,
                              LPVOID lpBits, BOOL MaskImage,
                              COLORREF FAR *crTransColor,
                              int Colors)
AniSprite                                             as_CreateMask  ---  41

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

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

         MaskImage   Boolean 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.

         crTransColor
                     Address of an array with the colours that are con-
                     sidered 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 using PALET-
                     TERGB 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 crTransColour 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
         crTransColour list is mapped to mask value 0 (opaque).

         This memory resource must be deleted with as_FreeResource.
42  ---  as_CropImage                                         ITB CompuPhase

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.

Syntax:  LPVOID as_CropImage(LPBITMAPINFO lpSrcInfo,
                             LPVOID lpSrcBits,
                             LPBITMAPINFO lpDstInfo,
                             LPRECT rc, BOOL DeleteSrc)

         lpSrcInfo   The BITMAPINFO header for the original DIB.

         lpSrcBits   The data for the original DIB.

         lpDstInfo   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 re-
                     source for lpSrcBits must have been allocated with
                     as_AllocResource.

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.
AniSprite                                            as_DeleteBoard  ---  43

See also:as_BoundingBox, as_ConvertImage, as_FreeResource


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

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

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_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 DeleteImage)

         Board       Identifies the board.

         DeleteImage If TRUE, as_DeleteBoard also frees the board image.
44  ---  as_ExpandMonoMask                                    ITB CompuPhase

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

See also:as_Assign, as_FreeResource



============================================================================
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 lpMonoBits)

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

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

-----------------------------
  2  EGI is a CompuPhase product.
AniSprite                                         as_ForwardMessage  ---  45

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 soldid colour.

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 rect-
                     angle 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.
46  ---  as_FreeResource                                      ITB CompuPhase

         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.

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

         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.

Returns: Always returns NULL.
AniSprite                                           as_GetBoardData  ---  47

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_CreateAlphaLevel, as_CreateLumaLevel, as_CreateMask, as_Delete,
         as_DeleteBoard, as_ExpandMonoMask



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

                     * AS_DATA_BOX
                       Returns the visible area of the board image in a RECT
                       structure; see lpVisRect in as_CreateBoard.

                     * AS_DATA_CANVASBITS
                       A pointer to the "scratch" DIB data. Each board
                       also has a scratch DIB (see page  6).

                     * AS_DATA_COLORTABLE
                       A pointer to the colour table that the board uses in
                       RGBQUAD format.

                     * AS_DATA_IMAGEBITS
                       A pointer to the board DIB data.
48  ---  as_GetBoardHandle                                    ITB CompuPhase

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

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

         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



============================================================================
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:
AniSprite                                          as_GetBoardValue  ---  49

                     * 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:

                     * AS_VALUE_HEIGHT
                       Returns the height of the animation board, which is
                       the height of visible part of the background image.

                     * 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
50  ---  as_GetData                                           ITB CompuPhase

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

                     * AS_VALUE_TIMERRES
                       Returns the actual timer resolution that was set for
                       the board by as_SetTimer.

                     * AS_VALUE_WIDTH
                       Returns the width of the animation board, which is
                       the width of visible part background image.

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

                     * AS_VALUE_YPOS
                       Returns the y-coordinate of the top side of the
                       animation board.

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

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

Errors:  AS_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.
AniSprite                                                as_GetData  ---  51

Syntax:  LPVOID as_GetData(ASPRITE Sprite, int Code, 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.

                     * AS_DATA_BOX
                       The bounding rectangle of the sprite (usually this
                       is the box around the complete sprite image); see
                       lpBoundingBox in as_Animate.

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

                       See page  14 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.

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

                     * AS_DATA_MASKBITS
                       Returns a pointer to the mask data in DIB format, or
                       NULL if the sprite has no mask.

                     * AS_DATA_MASTER
                       Returns the sprite to which the identified sprite is
                       linked.
52  ---  as_GetNearestColor                                   ITB CompuPhase

                     * AS_DATA_USERDATA
                       Returns a pointer to "user data".

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.

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
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.
AniSprite                                               as_GetValue  ---  53

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.

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.
54  ---  as_GetValue                                          ITB CompuPhase

                     * 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 con-
                       sidered "opaque".

                     * 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.
AniSprite                                         as_GrabSysPalette  ---  55

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)

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

         lpPalette   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.
56  ---  as_InBox                                             ITB CompuPhase

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



============================================================================
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 lpBox)

         Sprite      Identifies the sprite.

         lpBox       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.
AniSprite                                              as_LastError  ---  57

Returns: TRUE on success, FALSE on failure.

Errors:  AS_ERR_UNASSIGNED.

See also:as_Animate, as_GetData/AS_DATA_SPRITE



============================================================================
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)
58  ---  as_LevelInMask                                       ITB CompuPhase

         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.

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 lpMask, int Level)

         Width,
         Height      Dimensions of the masks.

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

         Level       The alpha or 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
AniSprite                                           as_MapMaskLevel  ---  59

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

         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_MapMaskLevel                     Change a mask level to a different level

as_MapMaskLevel changes all mask values 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_MapMaskLevel(int Width, int Height,
                              LPVOID lpMask, int From, int To)

         Width,
         Height      Dimensions of the masks.

         lpMask      The mask bits in 8-bpp DIB format.

         From        The mask value to change.

         To          The new mask value.
60  ---  as_Move                                              ITB CompuPhase

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)
AniSprite                                             as_PaintBoard  ---  61

         hDC         Microsoft Windows display context. If this handle is
                     NULL, function as_PaintBoard calculates the region of
                     areas that must be updated, but it does not actually
                     update the board (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 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  6.

         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.

         To calculate the region of changes for a board, call as_PaintBoard
         with the hDC parameter set to NULL. as_PaintBoard does not call the
         callback functions in this case. You can access rectangles from the
         region with as_GetBoardData/AS_DATA_REGIONRECT.
62  ---  as_PtInBoard                                         ITB CompuPhase

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.

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.
AniSprite                                           as_ReleaseTimer  ---  63

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  7 and
the optimization tips on page  18).

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

         Width,
         Height      Dimensions of the masks.

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

         Board       The board.

Returns: TRUE on success and FALSE on failure.

Errors:  AS_ERR_INVALIDOPERATION.
64  ---  as_ReplaceBoard                                      ITB CompuPhase

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 lpBits, LPRECT lpVisRect,
                              LPRECT lpInvalidRect)

         Board       Identifies the board.

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

         lpBits      The new board image bits.

         lpVisRect   Visible part of the new board image.

         lpInvalidRect
                     Part of board image that changes as a consequence
                     of the animation. When all of the image changes, set
                     lpInvalidRect to NULL.

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

Errors:  AS_ERR_MEMORY.

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
AniSprite                                           as_SetBoardData  ---  65

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

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

         Value       The data pointer that must be set.

Returns: TRUE on success and FALSE on failure.
66  ---  as_SetData                                           ITB CompuPhase

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.

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

                     * AS_DATA_USERDATA
                       Set "user data". The pointer can be used for any
                       purpose.

         Index       Depends on the Code parameter.
AniSprite                                             as_SetPalette  ---  67

         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.

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.
68  ---  as_SetPalette                                        ITB CompuPhase

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

         Board       The board handle.

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

         IdentityPalette
                     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 lpPal 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(lpBitsInfo, lpBits, NULL, 0L);
             as_SetPalette(Board, lpBitsInfo->bmiColors, TRUE);

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

See also:as_CreateBoard, as_GetBoardHandle
AniSprite                                               as_SetTimer  ---  69

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

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.
70  ---  as_SetValue                                          ITB CompuPhase

         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



============================================================================
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.
AniSprite                                                   as_Show  ---  71

         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.

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.
72  ---  as_SmoothMask                                        ITB CompuPhase

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 doesn't change the screen contents.

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 lpMask,
                            int Feather, int Levels)

         Width,
         Height      Dimensions of the masks.

         lpMask      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.
AniSprite                                            as_SpriteAtPos  ---  73

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 para-
                     meter 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.

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
74  ---  Error codes                                          ITB CompuPhase

                                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 anima-
          tion 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.
AniSprite                                               Error codes  ---  75

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

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.
76  ---  Error codes                                          ITB CompuPhase

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.
AniSprite                                  Using AniSprite with EGI  ---  77

                          Using AniSprite with EGI                Appendix B

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

EGI is a frame based animation engine, developed by CompuPhase. The anima-
tion 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 C 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.
78  ---  Using AniSprite with EGI                             ITB CompuPhase

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

      lpImage = FlicGetData(Flic, FLIC_DATA_BITMAP);
      lpMask = FlicGetData(Flic, FLIC_DATA_MASK);
      width = FlicGetParam(Flic, FLIC_PARAM_WIDTH);
      height = FlicGetParam(Flic, FLIC_PARAM_HEIGHT);

      Sprite = as_Create(width, height, lpMask,
                         AS_MASK_CUTOUT, lpImage, 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:
AniSprite                                  Using AniSprite with EGI  ---  79

----------------------------------------------------------------------------
  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.
80  ---  Getting more information                             ITB CompuPhase

                          Getting more information                Appendix C

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

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.
* 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  ---  81

                                    Index

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


                                         C language, 9
                                         Callback, 51
                                         Callback functions, 14, 66
Action, 3, 6                               Collision,D17DB, 15, 61
  buffered, 6                              DIB, 16
Alpha                                      Timer, 17
  blending, 3, 35, 37                    Cel animation, See Frame animation
  level, 14, 18, 35, 65, 72              Collision detection, 3, 17, 31, 32
  mask, 8, 72                            Colour models, 80
Animation                                Coordinates, 6
  external, 2                            Cutout mask, 3, 7, 19
  internal, 2, 77
Anti-aliasing, 72
as_ForwardMessage, 17                    DDB,b15,o55ard, 29
AS_MODE_NODRAW, 61                         callback, 15, 61
AS_TIMER, 17, 69, 70                       format, 3
Autodesk Animator, 77                    DIB, 15, 19, 28, 33, 77
                                           callback, 16
                                           format, 4, 7
Binary mask, 7, 13                       DIB section, 38, 49, 61
BITMAPINFO, 16, 29, 33                   Differential encoding, 27
Board, 3, 6                              Display Context, 15, 61
  coordinates, 6
  image, 6
  layer, 10                              EGI, 2, 77
  masked, 39                             Examples, 24
Borland
  C++, 9, 25                             Fade effect, 11
Bounding box, 27, 30, 48                 Flare effect, 4, 40
bpp, 33, 44                              Forwarded messages, 45
Buffered actions, 6                      Frame animation, 2, 77
82  ---  Index                                                ITB CompuPhase


GDI, 15                                  Palette, 5, 8
Grab
  palette, 55                              adapt, 33
  screen, 55                               handle,i49dentity, 4, 19, 68
                                           index, 52
HBITMAP, 49                                Manager, 80
HDC, 61                                    message, 10
HiColor, 34                                mode, 38, 50
HPALETTE, 49                             Palette grab, 55
                                         Pro Motion, 77
                                         Programming examples, 24
Identity palette, 19
Invalid rectangle, 27
                                         RGBQUAD, 33, 68

Layer, 4, 10, 17
Linked sprite, 60, 67, 69                Scratch image, 6, 16, 18, 61
Linked sprites, 4, 59                    Screen grab, 55
Luma                                     SetTimer, 70
  blending, 4, 37, 39                    Shadow effect, 4, 40
  level, 18, 39, 65                      Slot, 5
  mask, 8                                Spotlight effect, See Flare effect
                                         Sprite
                                           action, 3, 6
Mask                                       animation, 2
  alpha, 8, 72                             collision, 3, 31, 32
  binary, 7, 13                            linked, 4, 59, 60, 67, 69
  capabilities, 9                          origin, 5, 53, 54, 67, 69
  cutout, 3, 7, 19, 72                   StretchDIBits, 38
  luma, 8
Masked board, 39
Messages                                 Timer, 70
  forwarded, 45                            callback, 17
Metric (colour), 80                      Translucent, 5
Microsoft                                True-Color, 34
  Visual C/C++, 9, 25
                                         User data, 52, 66
Opaque level, 5, 17, 32, 33, 54, 62,
  71
Origin, 5, 53, 54, 67, 69                Video for Windows, 77
AniSprite                                                     Index  ---  83

Watcom C/C++, 9, 25                      WM_PALETTECHANGED, 10
WM_PAINT, 10, 61                         WM_QUERYNEWPALETTE, 10
