GetImage - Learn To Code - PlayBASIC Documentation

GetImage

GetImage ImageNumber, XLeft, YTop, XRight, YBottom

Parameters:

    ImageNumber = The Index of the image that you wish to create.
    XLeft= The Top Left hand X coordinate of the grab area
    YTop = The Top Left hand Y coordinate of the grab area
    XRight = The Bottom Right Hand X coordinate of the grab area
    YBottom = The Bottom Right hand Y coordinate of the grab area

Returns: NONE

      The GetImage command allows us grab a rectangular region of pixels from the current surface (normally the screen, but it can be another image) and create a new image from it. This newly create image can then be used just as other image and inherits the properties of the image from which it was grabbed.

      When grabbing images pixel data, GetImage will attempt to keep the image format the same as the surface it was grabbed from. So if you're grabbing from a Video image, the new image will also be in Video memory, same it's it's an FX or AFX image.

      However, that's assuming the ImageNumber GetImage provide the command doesn't exist. If the image already exists, and the existing image has the same dimensions as the grab region, the image format will be unchanged and PlayBASIC will simply copy the pixel data (via CopyRect) from the current surface to the image you specify.

      One common usage for GetImage is to grab animation frames from a sprite sheet.

FACTS:

      * GetImage copies from either the screen or the image your currently rendering to.

      * The size of the image created is calculated like so Image Width= XRight-XLeft, Height = YBot-Ytop

      * You attempt to grab a larger area than the screen or image your currently render to, the grab area will be clipped accordingly.

      * The area parameters GetImage uses are Xleft/Ytop inclusive while XRight/Ybot are both none inclusive.

Mini Tutorial #1:

How to grab a copy of the screen.

; Set the screen to be windowed, 640x * 480y with a 16bit display depth.
  OpenScreen 640,480,16,1

; Get a Free Image Number ready for use.
  ScreenImage=GetFreeImage()

; Get The Image from the Screen
  GetImage ScreenImage,0,0,GetScreenWidth(),GetScreenHeight()

; Display the Stat's about this image.
  Print GetImageWidth(ScreenImage)
  Print GetImageHeight(ScreenImage)

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

This example would output.

  640
  480

Mini Tutorial #2 - Frame Sheet (Sprite Animation) :

This example shows a function that will load a collection of sprite animation frames stored in image into an of our choosing array. The main work horse of the example is the GrabFrames function. This function runs through the provided image and splits it into frames of users size. Once the frames have been grabbed and the image indexes placed in an array of our choosing, we can render the animation pretty easily. This this (cut'n'paste friendly) example

;*=--------------------------------------------=*
; Load Animation Frames
;*=--------------------------------------------=*
; get PlayBASIC compiler path to guess
; location of the help file media

  path$=ProgramDir$()+"\Help\Commands/Media/Animations\"

; Load our Sprite Animation frame sheet
  ExplossionFrameSheet=LoadNewImage(Path$+"Explosion-Frame-Sheet.png",2)



; Dim an array to hold our animations image indexes in
  Dim ExpossionAnimation(0)

; Call this Grab Frames function.
; This function runs through frame sheet
; and creates frames that at 64 by 64 in size
  Frames=GrabFrames(ExplossionFrameSheet, 64 ,64, ExpossionAnimation())


; Once we've grabbed the frame, we can delete the frame sheet
  DeleteImage ExplossionFrameSheet



; Tell PB to limit the number to syncs to 30 or less per second
  SetFPS 30


;*=--------------------------------------------=*
; Main Loop
;*=--------------------------------------------=*

  Do

   ; Clear the screen to Black
     Cls

   ; Bump the current frame  up to the next frame
     CurrentFrame=Mod(CurrentFrame+1,16)

   ; Draw this frame
     DrawImage ExpossionAnimation(1+CurrentFrame),200,200,false


   ;Show the newly drawn screen to the user
     Sync
  Loop     SpaceKey()=true


  End




Function GrabFrames(ThisIMage, FrameWidth , FrameHeight, Frames())

  If GetImageStatus(ThisImage)

   ; Remember the current render surface, as
   ; we're going to change surfaces
     OldSurface=GetSurface()

   ; Redirect All rendering to this image
     RenderToImage ThisImage


   ; Get the Images Width & Height
     IW=GetImageWidth(ThisIMage)
     IH=GetImageHeight(ThisIMage)

   ; clear this array
     Dim Frames(0)


   ; Loop through the image
     For Ylp=0 To (IH/FrameHeight)-1
        For Xlp=0 To (IW/FrameWidth)-1

         ; Calc the the X + Y coordinates of
         ; for the area of pixels we wish to
         ; grab
           X1=Xlp*FrameWidth
           X2=X1+FrameWidth

           Y1=Ylp*FrameHeight
           Y2=Y1+FrameHeight

           FrameCount=GetFreeCell(Frames())

           Frames(FrameCount) = GetFreeImage()

           GetImage Frames(FrameCount),x1,y1,x2,y2

        Next

     Next

   ; restore the original render surface
     RenderToImage OldSurface

  EndIf

EndFunction     FrameCount

Example Frame Sheet

Example Source: Download This Example

; Draw a Shaded (bright - dark) stip of green pixels down the left hand side of the screen.
  h= GetScreenHeight()
  r#=100.0/h
  For lp =0 To h
     DotC 0,lp,RGBFade($2f6f3f,(h-lp)*r#)
  Next

; Grab this column of pixels as an Image
  PixelColIMage=GetFreeImage()
  GetImage PixelColImage,0,0,1,h*2

; Tile this image all over the screen
  TileImage pixelColimage,0,0,0


  Ink $ffffff
  Print "Press Any Key To Exit"
  Sync
  WaitKey


Related Info:	CopyRect \| CreateImage \| DeleteImage \| DrawImage \| LoadImage \| RenderToImage \| TileImage :