GNU Sprite32 - API Reference

This document is a quick introduction to the Sprite32 API and class library.

Class SpriteAppWin:
==================

  SpriteAppWin(char *title,int cx,int cy);

Instantiates a SpriteAppWin with the string value of `title' in its title bar,
and with dimensions `cx' and `cy'.

  virtual ~SpriteAppWin();

Destroys a SpriteAppWin and frees the resources associated with it.

  void run();

Starts a SpriteAppWin's main loop. Events are processed, sprites are moved and
rendered, and the framebuffer is refreshed on each iteration. The function does
  not return until quit() is called.

  void quit();

Terminates a SpriteAppWin's main event loop.

  virtual void handleEvent(SpriteEvent *se);

Event handler for the SpriteEvent described by se. SpriteEvents represent
keypresses, mouse movements, and joystick actions, and are translated by the
SpriteAppWin's inner loop from whatever event model your windowing system uses
into this common model.

This function actually does nothing, and is meant to be overridden when you
subclass SpriteAppWin.

  int loadSpriteImage(char *data,SpriteImage *si);

Loads an image from a PPM file whose name is pointed to by data, and fills the
SpriteImage structure pointed to by si with data about the image, including
dimensions, color depth, and the actual pixels. SpriteImages are a
platform-independent way of storing image data in a manner that different
windowing systems can understand, and may have window-system-specific data
(e.g., an XImage) attached to them.

  void destroySpriteImage(SpriteImage *si);

Destroys a SpriteImage, including freeing the space allocated for the image's
bits and for its platform-dependent representation (if any).

  void addSprite(Sprite *s);

Adds a sprite to the end of the linked list of sprites for this window.

  void deleteSprite(Sprite *s);

Removes a sprite from the window's sprite list.

  Sprite *lastSprite();

Walks the list until the last sprite is reached. Slow, but rarely used.

  Sprite *firstSprite();

Returns the head of the sprite list.

  void placeSpriteBehind(Sprite *s1,Sprite *s2);

Removes s1 from the list and reinserts it so it is just before s2. This creates
the illusion of s1 being "behind" s2 when they are drawn to the screen.

  void setRenderBack(int rb);

Sets the render-background flag to the Boolean value given by rb. In some cases
where the on-screen display is particularly dynamic, rendering a static
background may be an unnecessary and time-consuming step.

  int renderBack();

Returns the current value of the render-background flag.

  SpriteImage* background();

A SpriteImage that represents the static background image that is drawn before
any sprites are.

  SpriteImage* buffer();

A SpriteImage that represents the frame buffer. This image is the same size as
the background image, and is always this.xSize() by this.ySize(), regardless of
the size of the window.

  int xSize();

Returns the width, in pixels, of the window (and the frame buffer).

  int ySize();

Returns the height, in pixels, of the window (and the frame buffer).


  int getRenType();

Returns the renderer type. Not used now.

Class Sprite:
============

  Sprite(SpriteAppWin *sw,float x,float y,SpriteImage *si,
	 unsigned int mf,unsigned int d);

Creates a Sprite and attaches it to the SpriteAppWin indicated by sw. The
sprite will have position x and y (in pixels) and have a shape described by
the SpriteImage si, which has mf frames in it. See changeShape below. The
number of jiffies it takes to advance to the next frame is given by d.

  virtual ~Sprite();

Destroys a sprite and removes it from the SpriteAppWin to which it was
attached.

  virtual void move();

Moves a sprite along its velocity vector <vx,vy>. Done on each frame refresh.
Not very interesting by itself. When overridden in a subclass, however, this
function essentially tells the sprite what to do next on each frame. Use it
to describe your game objects' own interesting and complex behavior. :)

  void moveTo(float newx,float newy);

Repositions a sprite at the coordinates given by <newx,newy>. Not overridable.

  void setMotion(float vx,float vy);

Sets a sprite's velocity vector at <vx,vy>.

  void setHotspot(int hx,int hy);

Sets a sprite's hotspot to hx,hy, relative to the sprite's upper-left corner.
The "hotspot" of a sprite is the point on the sprite that will be centered on
its screen position coordinates. For example, if you have a 32x32 sprite of a
ball and its hotspot is at (16,16), then calling moveTo(x,y) will place the
center of the ball on (x,y).

When a sprite is created its hotspot defaults to the upper left corner.

  virtual void render(SpriteImage *si);

Draws the sprite on the SpriteImage given by si (usually the framebuffer image
for a SpriteAppWin).

  void calculateSize();

Calculates a sprite's vertical size based on its SpriteImage and number of
frames (see setMaxFrames).

  virtual void changeShape(SpriteImage *si);

Changes a sprite's shape to the SpriteImage pointed to by si. If the new image
has more or fewer frames than the previous image, you should also change the
number of frames (see setMaxFrames). Otherwise, Bad Things will happen. :)

A sprite's SpriteImage may be a single frame of animation, or it may be
several arranged vertically in "film-strip" fashion within a single image.
The sprite's height is thus given by the formula (SpriteImage height /
number of frames). Whenever either of these is changed, calculateSize is
called to make sure the sprite appears with the correct size.

For example, let's say you create a sprite of a man walking. To construct the
animation sequence, you draw four frames of the man walking, then combine
them all into one PPM file with the frames arranged vertically, in increasing
order. You use SpriteAppWin::loadSpriteImage() to load the image into a
SpriteImage structure, then specify that structure in the constructor to
Sprite, along with a value of 4 for the mf parameter.  You can then use
changeShape and setMaxFrames to change to any other similar animation
sequence.

  void goBehind(Sprite *s);

Moves this sprite "behind" the sprite pointed to by s. See also
SpriteAppWin::PlaceSpriteBehind.

  void setAutoColTest(int n);

Sets a flag that determines whether this sprite will automatically check for
collisions with other sprites, to the given boolean value.

  int autoColTest();

Return the value of the auto-collision-detection flag for this sprite.

  int collisionTest(Sprite *s);

Checks to see if this sprite's bounding box is overlapping with that of the
sprite pointed to by s. Returns true if they overlap; false otherwise.

  virtual void onCollision(Sprite *);

This function is called whenever autoColTest() is true and this sprite collides
with another sprite - ANY sprite. It is designed to be overridden in
subclasses. You may want to screen for the kinds of sprites you're interested
in using dynamic_cast.

  void setMaxFrames(unsigned int m);

Sets the number of frames in this sprite's animation (see calculateSize).
Usually follows a call to changeShape.

  void setAutoAnimate(int a);

Sets a flag that determines whether this sprite will advance to the next frame
in an animation sequence automatically.

  void setFrame(unsigned int f);

Sets the current frame in this sprite's animation sequence to frame #f.

  void setDelay(unsigned int d);

Sets the number of jiffies (framebuffer refreshes) per frame advance for this
sprite.

  void nuke();

Destroys the sprite. Same as calling ~Sprite. Deprecated.

  float xPos();

Returns the X-coordinate of this sprites upper-left corner (in pixels).

  float yPos();

Returns the y-coordinate of this sprites upper-left corner (in pixels).

  int xSize();

Returns the width of the sprite (in pixels).

  int ySize();

Returns the width of the sprite (in pixels).

  int xHotspot();

Returns the x-coordinate of the sprite's hotspot (relative to upper left corner
of sprite).

  int yHotspot();

Returns the y-coordinate of the sprite's hotspot (relative to upper left corner
of sprite).

  float xVel();

Returns the horizontal component of the sprite's velocity vector (in
pixels/jiffy).

  float yVel();

Returns the horizontal component of the sprite's velocity vector (in
pixels/jiffy).

  Sprite *nextSprite();

Returns the next sprite in this SpriteAppWin's linked list.

  Sprite *prevSprite();

Returns the previous sprite in this SpriteAppWin's linked list.

  SpriteAppWin *hostWin();

Returns a pointer to the SpriteAppWin that this sprite belongs to.

Special Functions:
=================

  void ImageCopy(SpriteImage *source,
                 SpriteImage *dest,
	         int sx,
	         int sy,
	         int x,
	         int y,
	         int cx,
	         int cy,
	         int flags,
	         long key);

Copies a rectangular portion from the SpriteImage pointed to by source into
the SpriteImage pointed to by dest. The area to be copied has an upper left
corner at sx,sy in source, and is of size cx,cy. It will be copied with its
upper left corner at x,y in dest. The value of flags may also influence the
function's behavior; currently valid flags include:

          SIMG_USE_KEY: color value in parameter `key' will
                        show up as transparent

Special Structures:
==================

  typedef struct tagSpriteImage {
    unsigned int cx;    //width
    unsigned int cy;    //height
    unsigned int depth; //color depth
    unsigned int scan_length; //length of one scanline in bytes
    unsigned int endian;      //endianness
    void *bits;         //actual bits of image
    void *img;          //pointer to WS-dependent struct for this image
  } SpriteImage;

The SpriteImage structure holds a single, packed-pixel image of arbitrary depth
(actually, current support is only for 8, 15, 16, 24, and 32-bpp images). Each
sprite has a SpriteImage associated with it that represents its on-screen
appearance.

The img member of SpriteImage is a pointer to the structure that represents
the image on the specific window system being used. For example, the X11
renderer creates an XImage for each SpriteImage, and uses the XImage
representation with the XShm extension to draw the framebuffer on screen.

The img member may be NULL for SpriteImages which don't need a WS-dependent
representation.


  typedef struct tagSpriteEvent {
    int type; // type of event
    int x,y;  // x and y coordinates of event
    union {
      int code;  //key code or other event message code
      void *ptr; //pointer to a more complex parameter
    } param;
  } SpriteEvent;

The SpriteEvent structure represents a UI event. The SpriteAppWin class
receives input events from the windowing system, and translates them into
SpriteEvents. SpriteEvents provide a platform-independent way of receiving
and handling events from the windowing system (or, in some cases, by directly
polling the device driver).

SpriteEvents can have one of the following types: S32_NullEvent,
S32_RefreshEvent, S32_KeyPressEvent, S32_KeyReleaseEvent, S32_MouseMoveEvent,
or S32_GameMoveEvent.