SpriteHandle - Learn To Code - PlayBASIC Documentation

SpriteHandle

SpriteHandle SpriteIndex, Xhandle, Yhandle

Parameters:

    SpriteIndex = The identifier of the sprite you wish to create
    Xhandle = The handle offset along the X axis
    Yhandle = The handle offset along the Y axis

Returns: NONE

      SpriteHandle changes the display offset of a sprite. When a sprite is drawn, PlayBasic will render the sprites image data at the sprites current position, offset by it's handle. This allows us to change the point at which the image attaches onto the sprite. Sprite handles default to offset 0x, 0y. Which attach the image at it's top left hand coordinate. But you can can change these to any amount we like. They can even be outside of the image size, it doesn't matter.

      One of the most common needs for altering sprite handles occurs when we rotate a sprite, since we'll common want it to spin around it's center, rather than it's top left coordinate. While you can use SpriteHandle for that, it's recommended that you use CenterSpriteHandle since it's less work for you. Sprites can also automatically center their handles for you by activating AutoCenterSpriteHandle mode.

Example Settings

      For the sake of simplicity, lets assume we have sprite with an image that's 100 pixels wide and 200 pixels high.

  SpriteHandle  MySprite,   0 ,   0     ; handle default top left hand coordinate
  SpriteHandle  MySprite,-100 ,   0     ; handle top right hand coordinate
  SpriteHandle  MySprite,   0 ,-200     ; handle bottom left hand coordinate
  SpriteHandle  MySprite,-100 ,-200     ; handle bottom right hand coordinate
  SpriteHandle  MySprite, -50 ,-100     ; handle to the center of the image

FACTS:

      * SpriteHandles Default to 0x,0Y

      * See CenterSpriteHandle to center a sprite handles on it's current image.

      * See AutoCenterSpriteHandle for auto centering

Mini Tutorial:

Create sprite, set it's handle, read the handle values back.

; Create Sprite #1
  CreateSprite 1

; Set sprite #'1 handle to 50,60
  SpriteHandle 1,50,60

; Display this sprites newly set sprite handle offsets
  Print GetSpriteHandleX(1)
  Print GetSpriteHandleY(1)

; Display the Screen and wait for the user to press a key
  Sync
  WaitKey

This example would output.

  50
  60

Example Source: Download This Example

;---------------------------------------------------------------------
; SpriteHandle Example
;---------------------------------------------------------------------

; =========================================================
; First Create an Image with a circle pattern on it.
; =========================================================
  Size=95
  Circle_Image=NewImage(Size,Size)
  RenderToImage Circle_Image
  Randomize 47

  For lp=size/2 To 1 Step -1
     CircleC Size/2,Size/2,lp,1,255-(lp*2)
  Next
  RenderToScreen


; =========================================================
; Create 5 sprites
; ========================================================
  NumberOfSprites=5
  For ThisSprite=1 To NumberOfSprites
   ;CReate this sprite
     x=Rnd(GetScreenWidth()-size)
     y=Rnd(GetScreenHeight()-size)

     ThisSprite=NewSprite(x,y, Circle_Image)

   ; Randomly Set the Sprites Image Handle
     SpriteHandle ThisSprite,RndRange(-size,size),RndRange(-size,size)

  Next



; Tell PB to limit speed of the program to 30 Frames (updates) per second or bellow
  SetFPS 30



; Start out update loop
  Do
   ; Clear the Screen to back   0= rgb(0,0,0)
     Cls 0

   ; Display a message
     Ink $ff00
     Print "Render Sprites Manually and display the effects of handles"
     Print "==========================================================="


   ; Manually run through our created sprites and render them.  Displaying the sprites
   ; POSITION and it's
     For lp =1 To NumberOfSprites

      ; DRaw this sprite
        DrawSprite lp

      ;Display a bound box around where sprite POSITION and image would be
      ; normally be..
        Ink RGB(0,255,0)
        w=GetSpriteWidth(lp)
        h=GetSpriteWidth(lp)

        x=GetSpriteX(lp)
        y=GetSpriteY(lp)

        Line x,y,x+w,Y
        Line x+w,y,x+w,Y+h
        Line x+w,y+h,x,Y+h
        Line x,y,x,Y+h

        Circle x,y,5,1
        Text x,y,"Sprite Axis:"+Str$(lp)


      ; Get Sprites Handle offset
        Hx=GetSpriteHandleX(lp)
        Hy=GetSpriteHandleY(lp)

      ; Display a bounding box around where the sprites image is drawn after applying
      ; the sprites handle offset..

        x=x+hx
        y=y+hy
        Ink RGB (255,255,255)
        Line x,y,x+w,Y
        Line x+w,y,x+w,Y+h
        Line x+w,y+h,x,Y+h
        Line x,y,x,Y+h

        Text x,y,"Sprite Handle: x:"+Str$(hx)+" y:"+Str$(hy)

     Next


   ; Display the screen and loop back to the DO statement to continue the loop
     Sync
  Loop


Related Info:	AutoCenterSpriteHandle \| CenterSpriteHandle \| GetAutoCenterSpriteHandle \| GetSpriteHandleX \| GetSpriteHandleY \| SpriteImage :