### Poll

Good
4 (80%)
Ok
1 (20%)
Needs Revision
0 (0%)
Inappropriate
0 (0%)

Total Members Voted: 5

### Author Topic: A Tutorial on _PUTIMAGE 2  (Read 180 times)

#### OlDosLover

• Hero Member
• Posts: 3859
• OlDosLover
##### A Tutorial on _PUTIMAGE 2
« on: February 25, 2013, 09:03:26 AM »

Tutorial on _PUTIMAGE 2
Welcome to this second tutorial on _Putimage. I will attempt to simplify and demysterfy how and why this commands works. There will be standalone example programs that will help educate and illustrate the knowledge needed to master this command.

Last time we used an example scenerio that had the SOURCE the same size as the DESTINATION. You may be wondering what happens if you mix different sizes. Lets use two images. The first image will be 800 x 600 pixels in size and the second image will be 320 x 200 pixels in size. Our viewing window will be 640 x 480 and all at 32 bit color depth. To do this we would issue the command:
_PUTIMAGE ,SOURCE,DESTINATION

Here's an example with SOURCE = 800 x 600 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 1 or (11)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT "press a key to load this 800 x 600 pixel image into a 640 x 480 pixel screen"
dummy\$ = INPUT\$(1)
_PUTIMAGE , Image1&, Video&
SLEEP
SYSTEM
The reader will notice that there was no error. The picture appears on screen but it is shrunk to fit the 640 by 480 DESTINATION automatically. QB64 automatically fits the SOURCE to the DESTINATION by design.

Here's an example with SOURCE = 320 x 200 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 2 or (12)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT "press a key to load this 320 x 200 pixel image into a 640 x 480 pixel screen"
dummy\$ = INPUT\$(1)
_PUTIMAGE , Image1&, Video&
SLEEP
SYSTEM
The reader will notice that there was no error. The picture appears on screen but it has expanded to fit the 640 by 480 DESTINATION automatically. QB64 automatically fits the SOURCE to the DESTINATION by design.

So whats left? Well if we consult the wiki we have these not covered in the last tutorial:

Syntax:
_PUTIMAGE (dx1, dy1), source_handle,dest_handle, (sx1, sy1)-(sx2, sy2) 'portion of source to TL corner of destination
_PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle,(sx1, sy1) 'right side of source from TL corner to destination
_PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle, (sx1, sy1)-(sx2, sy2)

Lets deal with _PUTIMAGE (dx1, dy1), source_handle,dest_handle, (sx1, sy1)-(sx2, sy2) first. This command is saying Place all of the source and apply it to the top left corner of the DESTINATION surface. So we will use the 640 by 480 DESTINATION window and first load the 320 x 200 SOURCE image onto our  DESTINATION

Here's an example with SOURCE = 320 x 200 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 3 or (13)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT "press a key to load this 320 x 200 pixel image into a 640 x 480 pixel screen"
dummy\$ = INPUT\$(1)
_PUTIMAGE (0, 0), Image1&, Video&, (0, 0)-(319, 199)
SLEEP
SYSTEM

The reader will note that the image appears as SOURCE size (320 x 200) on the DESTINATION window without being expanded. We have blank space on our DESTINATION screen.

Here's an example with SOURCE = 800 x 600 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 4 or (14)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT "press a key to load this 800 x 600 pixel image into a 640 x 480 pixel screen"
dummy\$ = INPUT\$(1)
_PUTIMAGE (0, 0), Image1&, Video&, (0, 0)-(799, 599)
SLEEP
SYSTEM
The reader will note that the image appears as SOURCE size (800 x 600) on the DESTINATION window without being shrunk.  Note the loss of the number "15"  on our DESTINATION screen. Here QB64 is pasting only 640 x 480 pixels of the 800 x 600 pixels available.

Now its time to deal with the _PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle,(sx1, sy1) command. This command is saying Place over the entire DESTINATION screen the SOURCE ,applied from the right side of source from top left corner to destination

Here's an example with SOURCE = 320 x 200 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 5 or (15)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT "press a key to load this 320 x 200 pixel image into a 640 x 480 pixel screen"
dummy\$ = INPUT\$(1)
_PUTIMAGE (0, 0)-(639, 479), Image1&, Video&, (0, 0)
SLEEP
SYSTEM
The reader will note that the same sized SOURCE appears on the DESTINATION window at the same size of 320 x 200 , leaving blank space on our DESTINATION screen at the same time.

Here's an example with SOURCE = 800 x 600 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 6 or (16)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT "press a key to load this 800 x 600 pixel image into a 640 x 480 pixel screen"
dummy\$ = INPUT\$(1)
_PUTIMAGE (0, 0)-(639, 479), Image1&, Video&, (0, 0)
SLEEP
SYSTEM
The reader will note that the DESTINATION window is full and the SOURCE image appears to  been clipped , as evidenced by not showing the number "15". As far as i know QB64 does this by design.

So far all has worked a treat. What would happen if we used incorrect coordinates? Imagine a minus One Hundred (-100) and a Seven Hundred and Forty (740) instead of a Six Hundred and Forty (640) on our DESTINATION screen! Also imagine What would happen if we used incorrect coordinates on our SOURCE image like -50 to 50?We need a new image that will make identification of small changes much easier to see.

Here's an example with SOURCE = 800 x 600 to DESTINATION = 640 x 480 program:
Code: [Select]
REM     TUT 2 - 7 or (17)
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
IF Image1& = -1 THEN PRINT "Image not loaded": SLEEP: SYSTEM
SCREEN Video&
PRINT "This is our new 800 x 600 pixel images. Press a key to see"
dummy\$ = INPUT\$(1)
_PUTIMAGE , Image1&, Video&
_DELAY 1
PRINT " Press a key to continue"
dummy\$ = INPUT\$(1)
CLS
PRINT "Note this screen is 640 x 480 pixels and NOT the  same size as our image."
PRINT
PRINT "What would happen if we made our destination x1 minus 100?"
PRINT "What would happen if we made our destination x2 740?"
PRINT
PRINT "press a key to load this 800 x 600 pixel image into a 640 x 480 pixel screen"
PRINT "With the destination coords of (-100, 0)-(739, 479), Image1&, Video&, (0, 0)"
dummy\$ = INPUT\$(1)
_PUTIMAGE (-100, 0)-(739, 479), Image1&, Video&, (0, 0)
_DELAY 1
PRINT " Press a key to continue"
dummy\$ = INPUT\$(1)
CLS
PRINT "Lets try a range of coords that are incorrect and see what the differences are"
PRINT "We will do 5 attempts at a range of 50,100,150,200,250!"
PRINT "Which are all larger than our output screen and !!!"
PRINT "At 250 thats even bigger than our (640 + 250 = 890) image size!"
PRINT "This will only effect our DESTINATION !!!!"
PRINT
PRINT " Press a key to continue"
dummy\$ = INPUT\$(1)
GOSUB RiskyDestination

PRINT " Press a key to continue"
dummy\$ = INPUT\$(1)
CLS
PRINT "Lets try a range of coords that are incorrect and see what the differences are"
PRINT "We will do 5 attempts at a range of 10,20,30,40,50!"
PRINT "Which are all different than our source screen and !!!"
PRINT "At 50 thats strange!"
PRINT "This will only effect our SOURCE !!!!"
PRINT
PRINT " Press a key to continue"
dummy\$ = INPUT\$(1)
GOSUB RiskySource
SLEEP
SYSTEM

RiskyDestination:
FOR t = 50 TO 250 STEP 50
tt = -(t)
_PUTIMAGE (0 - t, 0)-(639 + t, 479), Image1&, Video&, (0 + (t \ 5), 0)
PRINT "Our DESTINATION coordinates are "; tt; " and "; t + 639
_DELAY 2
CLS
NEXT t
PRINT "Finished!"
RETURN

RiskySource:
FOR t = 10 TO 50 STEP 10
tt = -(t)
_PUTIMAGE (0, 0)-(639, 479), Image1&, Video&, (0 + tt, 0 + t)
PRINT "Our SOURCE coordinates are "; tt; " and "; t
_DELAY 2
CLS
NEXT t
PRINT "Finished!"
RETURN
The reader should note after viewing the complete new image that when viewing the image on the DESTINATION screen with -100 as x1 and 739 as x2 which is 100 pixels extra each way that we see more of the middle of the image. When we try a range of -250 to 250 extra pixels each way of the DESTINATION screen that we see the entire image move to the left and eventually expose blank screen. Now when we do this same type of incorrect coordinates of -50 to 50 extra pixels both sides of the SOURCE image we get the image moving to the right and upward!
So in summary , even with incorrect coordinates we dont get an error. Its possible on either the DESTINATION and or the SOURCE screen's ,that we may not get a picture as it is outside of the "correct" boundaries annd too far to be seen!

The only style of command left that hasn't been covered yet is the _PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle, (sx1, sy1)-(sx2, sy2). This command is saying put the selected size of the SOURCE (sx1, sy1)-(sx2, sy2) onto the selected size of the DESTINATION (dx1, dy1)-(dx2, dy2). This style allow the user to use sprite sheets and only place the selected sprite of the SOURCE to anywhere onto the DESTINATION screen goverened by the size required to be shown with the destination coordinates. This means any sprite can be scaled with careful adjustment of the destination coordinates. This will be the topic discussed in part 3.

OlDosLover.