PUTIMAGE

From QB64 Wiki
Revision as of 14:02, 11 January 2011 by imported>Clippy
Jump to navigation Jump to search

The _PUTIMAGE statement puts an area of a source image to an area of a destination image.


Syntax

_PUTIMAGE (dx1,dy1)-(dx2,dy2), [source_handle], [dest_handle], (sx1,sy1)-(sx2,sy2)

or…
_PUTIMAGE [,[source_handle] [,dest_handle]]
_PUTIMAGE (dx1,dy1) [,[source_handle] [,dest_handle]]
_PUTIMAGE (dx1,dy1)-(dx2,dy2) [,[source_handle] [,dest_handle]]
_PUTIMAGE (dx1,dy1) ,[source_handle], [dest_handle], (sx1,sy1)-(sx2,sy2)
_PUTIMAGE , [source_handle], [dest_handle], (sx1,sy1)-(sx2,sy2)
_PUTIMAGE (dx1,dy1)-(dx2,dy2) ,[source_handle] ,[dest_handle] ,(sx1,sy1)


Description

  • dx1 = the x coordinate of the leftmost pixel to begin the insertion of the source image.
  • dy1 = the y coordinate of the uppermost pixel to begin the insertion of the source image.
  • dx2 = the x coordinate at which the insertion will end - rightmost pixel.
  • dy2 = the y coordinate at which the insertion will end - downmost pixel.
  • srchandle& = the LONG handle of the source image (may be created with _NEWIMAGE).
  • desthandle = the LONG handle of the destination image (may be created with _NEWIMAGE).
  • sx1 = the x coordinate of the leftmost pixel to include of the source.
  • sy1 = the y coordinate of the uppermost pixel to include of the source.
  • sx2 = the x coordinate of the rightmost pixel to include of the source.
  • sy2 = the y coordinate of the downmost pixel to include of the source.
  • If the area of the source is bigger or smaller than the area of the destination then the image is adjusted to fit that area.
  • Supports 32 bit alpha blending, color key transparency, true type fonts, stretching, mirroring/flipping, and a variety of graphics file formats including gif, png, bmp & jpg.
  • All graphical surfaces, including screen pages, can be acted upon in the same manner, and are referred to as "images".
  • Handles are used to identify graphical surfaces. Positive values are used to refer to screen pages. -1 (negative one) indicates an invalid surface. It is recommended that image handles be stored in LONG variables. Passing an invalid handle generates an "Invalid handle" error. Font handles also use -1 to indicate an invalid font.
  • When handles are not passed (or cannot be passed) to subs/functions then the default destination image or source image is referenced. These are set to the active page when the SCREEN statement is called, but can be changed to any image. So it is possible to read from one image using POINT and write to a different one with PSET.
  • Currently, the only commands that reference the source image are POINT and _PUTIMAGE.
  • It is IMPORTANT to free discarded or unused images with _FREEIMAGE to prevent CPU memory overflow errors!


Example 1:

SCREEN 13 a& = _NEWIMAGE(640, 200, 13) ' creates a 640 * 200 image with the LONG handle a& _DEST a& ' makes image a& the default drawing output. LINE (10, 10)-(100, 100), 12, BF ' draws a filled box (BF) into destination _PUTIMAGE (0, 0)-(320, 200), a&, 0, (0, 0)-(320, 200)

Explanation: A graphics mode is set by using SCREEN 13 (256 colors).
A new image is created that is 640 X 200 big and uses the palette compatible with screen 13 (256 colors).
_DEST a& makes the image with handle 'a&' the default image to draw on instead of the screen (which is _DEST 0).
Next a filled box (BF) is drawn from 10, 10 to 20, 20 with white colour (15) to the destination image (set by _DEST a&)
Now we put the image from 0, 0 to 320, 200 from the image with the handle 'a&' to the screen (always handle 0) and puts this image into the coordinates 0, 0 to 320, 200. If we want to stretch the image we can alter these coordinates (do try this!)
Note: All arguments are optional. If you want to simply put the whole image of the source to the whole image of the destination then you omit the area (x, y)-(x2, y2) on both sides, the last line of the example can be replaced by _PUTIMAGE , a&, 0 which indeed will stretch the image since image a& is bigger than the screen (the screen is 320 * 200 and a& is 640 * 200)


Example 2: You don't need to do anything special to use a .PNG image with alpha/transparency. Here's a simple example:

SCREEN _NEWIMAGE(640, 480, 32) CLS , _RGB(0, 255, 0) i = _LOADIMAGE("QB64.PNG") 'see note below examples to get the image _PUTIMAGE (0, 0), i ' places image at upper left corner of window w/o stretching it

Explanation: When QB64 loads a 256 color .PNG file containing a transparent color, that color will be treated as transparent when _PUTIMAGE is used to put it onto another image. So actually, you can use a 256-color .PNG file containing transparency information in a 256 color screen mode in QB64.


Example 3: Flipping and enlarging an image with _PUTIMAGE by swapping or increasing the desination coordinates.

DEFLNG A-Z dest_handle = _NEWIMAGE(640, 480, 32) SCREEN dest_handle '32 bit Screen 12 dimensions source_handle = _LOADIMAGE("QB64.PNG", 32) dx1 = 0: dy1 = 0 dx2 = _WIDTH(source_handle) - 1: dy2 = _HEIGHT(source_handle) - 1 'image dimensions - 1 LOCATE 29, 33: PRINT "Press any Key!"; 'normal image coordinate values based on the dimensions of the image: _PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle LOCATE 20, 34: PRINT "Normal layout" LOCATE 24, 10: PRINT "_PUTIMAGE (dx1, dy1)-(dx2, dy2), source_handle, dest_handle" K$ = INPUT$(1) 'to flip the image on the x axis, swap the dx coordinate values: _PUTIMAGE (dx2, dy1)-(dx1, dy2), source_handle, dest_handle LOCATE 20, 34: PRINT "Flip by X axis" LOCATE 24, 10: PRINT "_PUTIMAGE (dx2, dy1)-(dx1, dy2), source_handle, dest_handle" K$ = INPUT$(1) 'to flip image on y axis, swap the dy coordinate values: _PUTIMAGE (dx1, dy2)-(dx2, dy1), source_handle, dest_handle LOCATE 20, 34: PRINT "Flip by Y axis" LOCATE 24, 10: PRINT "_PUTIMAGE (dx1, dy2)-(dx2, dy1), source_handle, dest_handle " K$ = INPUT$(1) 'to flip both, swap both the dx and dy coordinate values: _PUTIMAGE (dx2, dy2)-(dx1, dy1), source_handle, dest_handle LOCATE 20, 34: PRINT "Flip on both axis" LOCATE 24, 10: PRINT "_PUTIMAGE (dx2, dy2)-(dx1, dy1), source_handle, dest_handle" K$ = INPUT$(1) 'to enlarge, double the second set of values plus any offset of the first coordinates: _PUTIMAGE (dx1, dy1)-((2 * dx2) + dx1, (2 * dy2) + dy1), source_handle, dest_handle LOCATE 20, 34: PRINT "Double image size" LOCATE 24, 2: PRINT "_PUTIMAGE (dx1, dy1)-((2 * dx2) + dx1, (2 * dy2) + dy1), s_handle, d_handle END

Adapted from code by Darth Who
Note: The QB64.PNG Bee image used can be copied from the top of the Main Forum Page


See Examples:

Bitmaps (Bitmap Screenshots)

SAVEIMAGE (Converts Images to Bitmaps)


See also




Navigation:
Keyword Reference - Alphabetical
Keyword Reference - By Usage
Main Wiki Page