                      Sprite Engine Library Overview

                              Conal Elliott

                  Last modified Thu Mar 18 14:37:32 1999


General comments: the modules have C and C++ interfaces.  The former is
there purely for use from Haskell, which doesn't know about C++ name
mangling, etc.


Behavior

  Simple linear behaviors.  Does automatic interpolation.

DDrawEnv

  Abstraction for double-buffered, windowed, clipped, resizable DirectDraw
  use.

SimpleTablet

  Tablet support.  Simplifies Wintab interface.

Sprite

  The varieties of sprites and sprite trees.

VBlankHandler

  "Vertical blank" work.  Allows addition and removal of any number of
  "vblank handlers".  Each handler gets to do pre-vblank setup and
  during-vblank completion.  Runs in its own thread, trying to keep up
  with, but not exceed, the video refresh rate.  Well, not exactly,
  because Windows doesn't give the necessary vblank interrupt.  Instead,
  go for a fixed period.

SpriteEngine

  "Sprite engine" abstraction, built on VBlankJob.  Runs a DDrawEnv and
  keeps performance stats.  There can be any number of engines running
  simultaneously.

SpriteLib

  Open and close the library, set the OS timer resolution.

cdecls.h

  Simple defs for integration with C

ddcheck

  Error-checkers for DirectX.  Reports non-OK hresults into human-readable
  error message box.  (Should rename to dxcheck.)

ddhelp

  Helper functionality for DirectX.  (Should rename to dxhelp.)

ddutil

  Standard DDraw utilities: load bitmap, etc.

wave

  Standard utility for opening & reading wave files.

waveBuffer

  Turn a wave file name into a DirectSound a directsound buffer.

wintab.h

  Header for Wintab by LCS/Telegraphics

GlobalVar

  Macros for declaring and defining global variables



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

Using the sprite engine:

- Initialize the library:

    OpenSpriteLib(100 /*screenPixelsPerLength*/ );

- Per animation initialization, start up a new sprite engine passing an
  HWND and a sprite tree chain.

      SpriteEngine *pEngine = newSpriteEngine(hwnd, trees);
   
- On WM_PAINT, there's nothing to do, since the engine thread draws
  continuously.  It's probably a good idea to optimize the engine to stop
  drawing when nothing's changing.  In that case, you will need to do
  something in response to a Windows Draw event.

- On window resize, tell the engine, so that it can re-allocate DDraw
  surfaces.

      onResizeSpriteEngine(pEngine);

- On animation termination, just delete the engine.  If you're running in
  debug mode, you'll get frames-per-second statistics.

      delete pEngine;

- Close the library:

      CloseSpriteLib();

