superwaba.ext.xplat.game
Class Sprite

java.lang.Object
  |
  +--superwaba.ext.xplat.game.Sprite
Direct Known Subclasses:
AnimatedSprite

public class Sprite
extends Object

Class implementing a game Sprite.

A sprite is a graphical object typicaly used in games that can be moved, with collision detection feature and background saving/restoring capability.

The sprite attributes are:

  • position
    The sprite position centerX,centerY is in fact its center position.

  • size
    width/height contains respectively the image horizontal/vertical dimensions.

  • half size
    halfWidth/halfHeight contains respectively the half horizontal/vertical dimensions.

  • valid region
    The valid region of a sprite are relativ to the sprite center. The valid region can be provided in the Sprite constructor or by the setRegion call. Both are waba.fx.Rect objects. If null is passed in the constructor the default region is computed to prevent the sprite living even partially the screen.
    Once set the region can be modified by incrementing/decrementing the values of regionMinx, regionMiny, regionMaxx and regionMaxy

  • draw operation
    The default value of drawOp is DRAW_PAINT if its value is DRAW_PAINT the image is copied "as is" to the buffer, and
    if its value is DRAW_SPRITE the transparency color specified in the constructor is used to prevent the copy of image pixels of this color in order to preserve the background.

    You can find a complete game API sample named 'Ping' in the SW examples folder.
    Here is some sample code:

     // Ball is a the Sprite bouncing on the screen.
     // The ball bounces on the left, the top and the bottom border and
     // must be hit by the racket on the right border to keep the ball inside the screen.
     // If the racket misses the ball, the game is over.
    
     public final class Ball extends Sprite {
    
       // random generator for the starting speeds
       private Random rand=new Random();
    
       // keep a reference to the game mainclass for data access & game control.
       private Ping game;
    
       // other important sprite the ball sprite must know about for interaction...
       private Racket racket;
    
      // ball movement speed in both directions in double values for acceleration precision
      private double speedx,speedy;
    
      // and in integer format for quicker move computing.
      private int ispeedx,ispeedy;
    
       //----------------------------------------------------------------
       // Ball constructor.
       // @param game the Ping game mainclass.
       // @param racket Sprite that interacts with the ball.
       //----------------------------------------------------------------
    
       public Ball(Ping game,Racket racket) {
    
         // setup the sprite by loading the bitmap, defining the transparency color.
         // The ball element does not fill the whole bitmap, the corners are filled
         // with WHITE pixels. By setting WHITE as the transparency color and selecting the
         // DRAW_SPRITE draw mode, the bitmap white pixels are not shown and the background
         // is not affected by the bitmap display. The background saving feature is disabled
         // because the whole screen is cleared and redrawn at each frame. No valid region
         // (null) means, default valid region is right. Except that the miny value must be
         // incremented to prevent the ball hiding the score.
    
         super(new Image("ball.bmp"),Color.WHITE,false,null);
         drawOp=Graphics.DRAW_SPRITE;
    
         // the ball may go out of the window when the user misses it
         doClip = true;
    
         // by default the valid area of a sprite is the screen.
         // reduce the playfield of the racket by the level & score display zone
         regionMiny+=Ping.GAME_MINY;
    
         this.game=game;
         this.racket=racket;
    
         // initialize the ball
         reinit();
       }
    
       // initialization needed each time a game starts.
       // The racket is placed in the middle of the right border and the ball
       // is placed next to it.
       // Also defines the initial ball speed.
    
       public void reinit() {
    
         Coord pos=racket.getBallPosition(halfWidth);
         setPos(ballHitX=pos.x,pos.y,false);
    
         speedx=4+rand.nextFloat()*6.0f;
         speedy=2+rand.nextFloat()*3.0f;
         ispeedx=-1;
         ispeedy=-1;
    
         // the toward position specified in the towardPos call is not a
         // direction but an ending position, so speed is irrelevant.
    
         speed=1000;
         ...
       }
    
       //----------------------------------------------------------------
       // Move the ball to next position depending on the current speed.
       //----------------------------------------------------------------
    
       public void move() {
    
         // add the speed vector and enable position validation.
         // see the "Ping" sample code for more details about position validation.
         // this towardPos() moves the sprite toward a point, the third parameter
         // enables position validation which is needed for each position change to
         // precisely detect the racket or the borders hits.
         // This call could be optimized to disable the time consuming position
         // validation when the ball is not near the screen border.
    
         towardPos(centerX+ispeedx,centerY+ispeedy,true);
       }
     


    Field Summary
    protected  Image background
              Background image.
    protected  Graphics bgGfx
              Background graphic context.
    protected  int bgX
              Background restoring position.
    protected  int bgY
              Background restoring position.
     int centerX
              Sprite center position.
     int centerY
              Sprite center position.
     boolean doClip
              set to false if this sprite never reaches the screen boundaries.
     int drawOp
              The sprite drawOp.
    protected  Graphics gfx
              Graphics to draw at.
    protected  int halfHeight
              Sprite half width/height dimensions.
    protected  int halfWidth
              Sprite half width/height dimensions.
     int height
              Sprite width/height dimensions.
    protected  Image image
              Sprite image.
    protected static int INVALID
               
    protected  int regionMaxx
              Sprite valid region.
    protected  int regionMaxy
              Sprite valid region.
    protected  int regionMinx
              Sprite valid region.
    protected  int regionMiny
              Sprite valid region.
    protected  boolean screenErased
               
     int speed
              Speed in pixels used by the function towardPos.
    protected  ISurface surface
              Surface to draw at.
    protected  Color transColor
              cached image transparency color
     int width
              Sprite width/height dimensions.
     
    Constructor Summary
    protected Sprite(Image image, Color transColor, boolean saveBckgd, Rect region)
              Sprite constructor.
     
    Method Summary
     boolean collide(Sprite s)
              Test if the sprite collides with another one.
     Coord getPos()
              Retrieve the sprite position (actually its center).
     Rect getRegion()
              Retrieve the sprite valid region.
     void hide()
              Restore the sprite's saved background.
     boolean onPositionChange()
              Default position validation function.
     boolean setPos(int x, int y, boolean doValidate)
              Sets the sprite position (actually its center).
     void setRegion(Rect region)
              Change the sprite valid region.
     void show()
              Draw the sprite at it's current position using the defined drawOp.
     boolean towardPos(int x, int y, boolean doValidate)
              Moves the sprite toward the specified position.
     
    Methods inherited from class java.lang.Object
    equals, getClass, hashCode, notify, toString, wait, wait
     

    Field Detail

    centerX

    public int centerX
    Sprite center position.

    centerY

    public int centerY
    Sprite center position.

    width

    public int width
    Sprite width/height dimensions. READ-ONLY attributes.

    height

    public int height
    Sprite width/height dimensions. READ-ONLY attributes.

    halfWidth

    protected int halfWidth
    Sprite half width/height dimensions. READ-ONLY attributes.

    halfHeight

    protected int halfHeight
    Sprite half width/height dimensions. READ-ONLY attributes.

    regionMinx

    protected int regionMinx
    Sprite valid region.
    The sprite cannot leave this area if the default position validation function is not overriden.
    See Also:
    onPositionChange()

    regionMiny

    protected int regionMiny
    Sprite valid region.
    The sprite cannot leave this area if the default position validation function is not overriden.
    See Also:
    onPositionChange()

    regionMaxx

    protected int regionMaxx
    Sprite valid region.
    The sprite cannot leave this area if the default position validation function is not overriden.
    See Also:
    onPositionChange()

    regionMaxy

    protected int regionMaxy
    Sprite valid region.
    The sprite cannot leave this area if the default position validation function is not overriden.
    See Also:
    onPositionChange()

    image

    protected Image image
    Sprite image.

    gfx

    protected Graphics gfx
    Graphics to draw at.

    surface

    protected ISurface surface
    Surface to draw at.

    drawOp

    public int drawOp
    The sprite drawOp.
    if the drawOp is set to DRAW_SPRITE, the sprite is drawn and the background is not erased where the sprite image pixels have the transparent color. Valid values are DRAW_PAINT and DRAW_SPRITE.
    See Also:
    Graphics

    speed

    public int speed
    Speed in pixels used by the function towardPos.
    See Also:
    towardPos(int, int, boolean)

    transColor

    protected Color transColor
    cached image transparency color

    screenErased

    protected boolean screenErased

    doClip

    public boolean doClip
    set to false if this sprite never reaches the screen boundaries. Default is true.

    INVALID

    protected static final int INVALID

    background

    protected Image background
    Background image.

    bgGfx

    protected Graphics bgGfx
    Background graphic context.

    bgX

    protected int bgX
    Background restoring position.

    bgY

    protected int bgY
    Background restoring position.
    Constructor Detail

    Sprite

    protected Sprite(Image image,
                     Color transColor,
                     boolean saveBckgd,
                     Rect region)
    Sprite constructor.
    Parameters:
    image - sprite image.
    transColor - sprite's transparency color or null if none
    (needed in DRAW_SPRITE mode to keep the current background).
    saveBckgd - true if the background should be saved each time the sprite is drawn to restore it once the sprite moves.
    region - defines the sprite valid area.
    If null, a default region is set to prevent the sprite to leave even partially the screen.
    Method Detail

    getRegion

    public final Rect getRegion()
    Retrieve the sprite valid region.
    NOTE: should be called cautiously due to a Rect object alloc.
    Returns:
    positions validity region

    setRegion

    public final void setRegion(Rect region)
    Change the sprite valid region.
    Parameters:
    region - new positions validity area

    onPositionChange

    public boolean onPositionChange()
    Default position validation function.
    This function can be overloaded to define your own sprite position validation or collision detection.
    The overloaded function may use the sprite data members and should update the sprite position centerX and centerY if needed.
    Returns:
    true if the (centerX,centerY) is a valid position, false if it's not and the position has been corrected.
    NOTE: false returns will stop the movements of the towardPos function.
    See Also:
    towardPos(int, int, boolean)

    setPos

    public final boolean setPos(int x,
                                int y,
                                boolean doValidate)
    Sets the sprite position (actually its center).
    Note: if doValidate is false, you may consider just setting centerX and centerY attributes directly (it is 60% faster).
    Parameters:
    x - position.
    y - position.
    doValidate - if true the position is validated which means that the onPositionChange() function is called.
    Returns:
    true if the defined position has been set
    See Also:
    onPositionChange()

    getPos

    public final Coord getPos()
    Retrieve the sprite position (actually its center).
    NOTE: should be called cautiously due to a Coord object alloc. You may also consider accessing the centerX and centerY directly.
    Returns:
    sprite's center position

    towardPos

    public boolean towardPos(int x,
                             int y,
                             boolean doValidate)
    Moves the sprite toward the specified position.
    This function is typically used when the user points the end position with the pen. The object position is computed to move smoothly from it's current position to the target position.
    Parameters:
    x - position.
    y - position.
    doValidate - if true the position is validated which means that the onPositionChange() function is called.
    NOTE: a false return of onPositionChange() will stop the towardPos function.
    Returns:
    true if the defined position has been set
    See Also:
    onPositionChange()

    show

    public void show()
    Draw the sprite at it's current position using the defined drawOp.
    If the Sprite has been created with enabled background saving (usefull only when the screen is not cleared before the new frame display) the previously stored background will be restored first and the sprite is displayed in a second step.
    NOTE: if several sprite moves simultaneously and may overlap the background restoring may erase a previously drawn sprite. In this case, the only solution is to call explicitly the hide() function on all the sprites in the DRAWN REVERSE ORDER.
    By doing so, you always restore a clean image without sprites before starting a new draw cycle of all the sprites.

    hide

    public void hide()
    Restore the sprite's saved background.
    NOTE: the position may have change, the saved background position has been memorized also, to restore it at the right place.

    collide

    public boolean collide(Sprite s)
    Test if the sprite collides with another one.
    Parameters:
    s - sprite to test with
    Returns:
    true if both sprite overlaps, false otherwise