Poll

"Please rate this tutorial..."

Good
4 (100%)
Ok
0 (0%)
Needs Revision
0 (0%)
Inappropriate
0 (0%)

Total Members Voted: 4

  • Print

Author Topic: A Tutorial on _PUTIMAGE 1  (Read 213 times)

OlDosLover

  • Hero Member
  • *****
  • Posts: 3859
  • OlDosLover
    • Email
A Tutorial on _PUTIMAGE 1
« on: February 24, 2013, 06:58:48 AM »
               
Tutorial on _PUTIMAGE 1
[/size]
    Welcome to this tutorial on _Putimage. I will attempt to simplify and demysterify 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.

    If we consult the wiki we get this explanation:
The _PUTIMAGE statement puts an area of a source image to an area of a destination image in one operation like GET and PUT.

    The first two significant words used here are SOURCE and DESTINATION. Imagining we have an image thats loaded and available in memory ready to go , then this is our SOURCE. Imagining we have an output display window that the user is looking at for program results , then this is our DESTINATION. In wiki terms the GET is from the SOURCE and the PUT is to the DESTINATION. My examples will centre around putting a SOURCE image to a DESTINATION window. However one could use the _Putimage command to simply place images across different surfaces that aren't necessarily seen on an output window.

    It should be noted here that _PUTIMAGE can not get and put to the same surface or in other words be the same SOURCE and DESTINATION places. If you try this you will get an error as this program will illustrate!

Code: [Select]
REM     TUT1
DEFLNG A-Z
SCREEN _NEWIMAGE(640, 480, 32)
GOSUB MakBox
_DELAY 1
LOCATE 1, 1
PRINT "Press a key to see how we will make another box at another place like this:"
LINE (30, 30)-(130, 130), _RGB32(255, 255, 0), BF
dummy$ = INPUT$(1)
CLS
GOSUB MakBox
PRINT "Note the : Line 14 , Illegal function call (Unhandled Error#5) error!"
_PUTIMAGE (30, 30)-(130, 130), 0, 0, (270, 190)-(370, 290)
SLEEP
SYSTEM

MakBox:
LINE (270, 190)-(370, 290), _RGB32(255, 255, 0), BF
RETURN

    So moving on we come to the wiki syntax:
Syntax:
_PUTIMAGE [(dx1, dy1)[-(dx2, dy2)]][, source_handle][, dest_handle][, (sx1, sy1)[-(sx2, sy2)]]
or…
_PUTIMAGE 'full source image to fit full destination area after _SOURCE and _DEST are set
_PUTIMAGE , source_handle, dest_handle 'size full source to fit full destination area
_PUTIMAGE (dx1, dy1), source_handle, dest_handle 'full source to TL corner destination position
_PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle 'size full source to destination coordinate area
_PUTIMAGE (dx1, dy1), source_handle,dest_handle, (sx1, sy1)-(sx2, sy2) 'portion of source to TL corner of destination
_PUTIMAGE , source_handle, dest_handle, (sx1, sy1)-(sx2, sy2) 'portion of source to full destination area
_PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle,(sx1, sy1) 'right side of source from TL corner to destination

Note: The Top Left corner position designates the leftmost and top-most portion of the image to use.

    What we immediately notice is the myriad of different ways we can use this command. So lets experiment with each of them one by one. We will start with a simple concept. The SOURCE image is the same size as the DESTINATION screen.
Syntax:
_PUTIMAGE , source_handle, dest_handle 'size full source to fit full destination area

    So in our example our Output Screen's handle (DESTINATION) is Video& and our Loaded Image's handle (SOURCE) is Image1& ,and they are both of the same size, we would simply issue the command:
_PUTIMAGE , Image1&, Video&

Code: [Select]
REM    TUT2
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1a.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels the same size as our image."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&
SLEEP
SYSTEM

    Now lets introduce the idea to place our complete SOURCE image onto only half of our DESTINATION screen. To do this we need to use the [(dx1, dy1)[-(dx2, dy2)] coordinates for the DESTINATION screen only. Therefore our command would look like this:
_PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle

    As we only want to cover half of this output window ,therefore our x1 and x2 length is half of the image's x1 and x2 length. As both our SOURCE and DESTINATION are the same size and thats 640 pixels then half is only 320 pixels. So we would issue the command:
_PUTIMAGE (0, 0)-(319, 479), Image1&, Video&
Note that we are using (640 \ 2 = 320)  as 0 to 319 on the X axis to only cover half the output window. Here's an example program:

Code: [Select]
REM   TUT3
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1a.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
SCREEN Video&
PRINT "Note we will only cover half of the X axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE (0, 0)-(319, 479), Image1&, Video&
SLEEP
SYSTEM

    As we only want to cover half of this output window ,therefore our y1 and y2 length is half of the image's y1 and y2 length. As both our SOURCE and DESTINATION are the same size and thats 480 pixels then half is only 240 pixels. So we would issue the command:
_PUTIMAGE (0, 0)-(639, 239), Image1&, Video&
Note that we are using (480 \ 2 = 240)  as 0 to 239 on the Y axis to only cover half the output window. Here's an example program:
Code: [Select]
REM    TUT4
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1a.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
SCREEN Video&
PRINT "Note we will only cover half of the Y axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE (0, 0)-(639, 239), Image1&, Video&
SLEEP
SYSTEM

    To cover one quarter of the output window at a time regulated by a key press , we would have to copy to the top left corner first , then copy to the top right corner , then copy to the bottom left corner ,then copy to the bottom right corner last. These commands would look like this:
Top Left corner DESTINATION = _PUTIMAGE (0,0)-(319,239), Image1&, Video&
Top Right corner DESTINATION = _PUTIMAGE (320,0)-(639,239), Image1&, Video&
Bottom Left corner DESTINATION = _PUTIMAGE (0,240)-(319,479), Image1&, Video&
Bottom Right corner DESTINATION = _PUTIMAGE (320,240)-(639,479), Image1&, Video&
    And an example program to illustrate this is:
Code: [Select]
REM    TUT5
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1a.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
WWidth& = _WIDTH(Image1&)
HHeight& = _HEIGHT(Image1&)
SCREEN Video&
CLS
LOCATE 24, 1
PRINT "Note we will only cover half of the X axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE (0, 0)-(WWidth& \ 2, HHeight&), Image1&, Video&
_DELAY 1
CLS
LOCATE 24, 1
PRINT "Note we will only cover half of the Y axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE (0, 0)-(WWidth&, HHeight& \ 2), Image1&, Video&
_DELAY 1
CLS
LOCATE 23, 1
PRINT "Note we will only cover half of the X axis."
PRINT "Note we will only cover half of the Y axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE (0, 0)-(WWidth& \ 2, HHeight& \ 2), Image1&, Video&
_DELAY 1
CLS
LOCATE 23, 1
PRINT "Note we will tile the screen with several copies of our image"
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE (0, 0)-(WWidth& \ 2, HHeight& \ 2), Image1&, Video&
_DELAY 1
_PUTIMAGE (WWidth& \ 2, HHeight& \ 2)-(WWidth&, HHeight&), Image1&, Video&
_DELAY 1
_PUTIMAGE (0, HHeight& \ 2)-(WWidth& \ 2, HHeight&), Image1&, Video&
_DELAY 1
_PUTIMAGE (WWidth& \ 2, 0)-(WWidth, HHeight& \ 2), Image1&, Video&
_DELAY 1
PRINT "Press a key to END": dummy$ = INPUT$(1)
SYSTEM
    These example programs illustrate that the full SOURCE is pasted onto a part of the DESTINATION window , decided by the use of the destination coordintes
(dx1, dy1)-(dx2, dy2) . In summary the reader could say we are shrinking all the source to fit part of the destination window.


    Now lets introduce the idea to place part of our  SOURCE image onto the complete DESTINATION screen. To do this we need to use the
[(sx1, sy1)-(sx2, sy2)] coordinates for the SOURCE screen only. As we want to cover all of the output window we can leave out the [(dx1, dy1)[-(dx2, dy2)] part of the command. Therefor our command will look like this:
_PUTIMAGE , source_handle, dest_handle, (sx1, sy1)-(sx2, sy2)
Here is the full display of our entire SOURCE image that has changed from the one used previously. The example program:
   
Code: [Select]
REM    TUT6
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1b.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
SCREEN Video&
PRINT "Note this screen is 640 x 480 pixels the same size as our image."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&
SLEEP
SYSTEM

    As we would like to only see the top half of our source image on the destination screen we would issue the command:
_PUTIMAGE , Image1&, Video&, (0, 0)-(319, 479)
Note the (0 - 319) which is 320 pixels that is half of our SOURCE images horizontal size. The (0 - 479) is 480 pixels which is the entire vertical size of our SOURCE

Code: [Select]
    TUT7
REM
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1b.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
SCREEN Video&
PRINT "Note we will only cover half of the X axis of the SOURCE."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&, (0, 0)-(319, 479)
SLEEP
SYSTEM

    As we would like to only see the left half of our source image on the destination screen we would issue the command:
_PUTIMAGE , Image1&, Video&, (0, 0)-(639, 239)
Note the (0 - 639) is 640 pixels the same horizontal size as the SOURCE image. The (0 - 239) is 240 pixels which is half of the vertical size of the SOURCE

Code: [Select]
REM  TUT8
DEFLNG A-Z
Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1b.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"
SCREEN Video&
PRINT "Note we will only cover half of the Y axis of the SOURCE."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&, (0, 0)-(639, 239)
SLEEP
SYSTEM

    To paste sections of the SOURCE image to the entire DESTINATION window regulated by a key press , we would have to copy from the top left corner first , then copy from the top right corner , then copy from the bottom left corner ,then copy from the bottom right corner last. These commands would look like this:
Top Left corner SOURCE = _PUTIMAGE , Image1&, Video& , (0,0)-(319,239)
Top Right corner SOURCE = _PUTIMAGE , Image1&, Video& , (319,239)-(639,479)
Bottom Left corner SOURCE = _PUTIMAGE , Image1&, Video& , (0,239)-(319,479)
Bottom Right corner SOURCE = _PUTIMAGE , Image1&, Video& ,(319,0)-(639,239)
    And an example program to illustrate this is:
Code: [Select]
REM
DEFLNG A-Z

Video& = _NEWIMAGE(640, 480, 32)
Image1& = _LOADIMAGE("Tut2ExampleImage1b.png", 32)
IF Image1& = -1 THEN PRINT "Image not loaded"

WWidth& = _WIDTH(Image1&)
HHeight& = _HEIGHT(Image1&)

SCREEN Video&
PRINT "Here's our entire image same size SOURCE to same size DESTINATION"
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&
_DELAY 1

CLS
LOCATE 24, 1
PRINT "Note we will only cover half of the X axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&, (0, 0)-(WWidth& \ 2, HHeight&)
_DELAY 1

CLS
LOCATE 24, 1
PRINT "Note we will only cover half of the Y axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&, (0, 0)-(WWidth&, HHeight& \ 2)
_DELAY 1

CLS
LOCATE 23, 1
PRINT "Note we will only cover half of the X axis."
PRINT "Note we will only cover half of the Y axis."
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&, (0, 0)-(WWidth& \ 2, HHeight& \ 2)
_DELAY 1

CLS
LOCATE 23, 1
PRINT "Note we will tile the screen with several copies of our image"
PRINT "press a key to load this image"
dummy$ = INPUT$(1)
_PUTIMAGE , Image1&, Video&, (0, 0)-(WWidth& \ 2, HHeight& \ 2)
_DELAY 1
_PUTIMAGE , Image1&, Video&, (WWidth& \ 2, HHeight& \ 2)-(WWidth&, HHeight&)
_DELAY 1
_PUTIMAGE , Image1&, Video&, (0, HHeight& \ 2)-(WWidth& \ 2, HHeight&)
_DELAY 1
_PUTIMAGE , Image1&, Video&, (WWidth& \ 2, 0)-(WWidth, HHeight& \ 2)
_DELAY 1

PRINT "Press a key to END": dummy$ = INPUT$(1)
SYSTEM


These example programs illustrate that part of the SOURCE is pasted onto the entire DESTINATION window , decided by the use of the destination coordintes
(sx1, sy1)[-(sx2, sy2) . In summary the reader could say we are expanding part of  the source to fill  the entire destination window.

You will need the two Attachments inside the archive of the complete tutorial.
OlDosLover.



  • Print