Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

  Overview | Package | Class | Tree | Deprecated | Index | Help
  PREV CLASS NEXT CLASS | FRAMES NO FRAMES
  SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD