PUT (graphics statement)
The PUT graphics statement is used to place GET or BSAVE file images stored in the designated array.
Syntax
- The STEP keyword can be used to for coordinates relative to the last graphic coordinates used.
- column and row INTEGER coordinate values designate the top left corner where the image is to be placed and cannot be off screen.
- The INTEGER array holds data of an image box area created by GET. The brackets can be empty or designate a starting index.
- _CLIP can be used in QB64 when part of an image must be off screen.
- XOR, PSET, PRESET, OR or AND actions will affect the coloring of the image on certain background colors. See below.
- omitcolor is the pixel color attribute to ignore in QB64 only. This may be used instead of using an AND mask.
Usage:
- The entire box area of the image MUST be on the screen or an "Illegal function call" error will occur!
- In QB64 _CLIP can be used when part of the image may be off of the screen. This will also prevent off screen errors!
- PUT (-10, 10), mypic(0), PSET ' this causes an illegal function call without _CLIP
- PUT (-10, 10), mypic(0), _CLIP PSET ' allows a graphic to be placed partially off-screen
- PUT (-10, 10), mypic(0), _CLIP ' uses the default PUT XOR operation
- PUT (-10, 10), mypic(0), _CLIP PSET, 4 ' doesn't place the red pixels of the image
- In QB64 a background color attribute can be removed from the PUT image using the omit color option instead of creating a mask.
- The array must have image data at the array index given. GET or BLOAD should be used to place image data into the array.
- The INTEGER array size can be calculated as slightly larger than the box area width times the height. A closer estimate can be done by reading the array indices from UBOUND to LBOUND after a GET of a white box area. In QB64 a LONG array can be used for large or full screen images.
- If no array index (brackets optional in QB) is designated, the image will be assumed to be at the array's starting index.
- The first two indices of the array or array offset will hold the width and height of the stored image area. In SCREEN 13 divide the width by 8.
- More than one image can be stored in the INTEGER array by indexing the GET array offset. Be sure the index is not already used!
- A _DEST handle can be set to PUT images elsewhere other than on the current screen. Use _SOURCE to GET images there.
- If no color action is listed after the image array, the action will be assumed to be the default XOR.
- XOR may blend with background colors, but can be used to erase an image when placed a second time.
- PSET completely overwrites any background with the identical image.
- PRESET creates a inverted coloring of the original image completely overwriting the background.
- AND merges background colors with the black areas of the image where a white image mask is used.
- OR blends the background and foreground colors together.
- In QB64 _PUTIMAGE is recommended over PUT as it can also do the GET directly from the image source without requiring an array.
- PUT and GET file statements can also write and read image array data using BINARY files instead of using BSAVE or BLOAD.
Example 1: How GET and PUT can be used with images loaded with _LOADIMAGE. The background color is omitted or "masked".
SCREEN _NEWIMAGE(640, 480, 256) _SCREENMOVE _MIDDLE image& = _LOADIMAGE("QB64.png") 'QB64 bee image from Forum wide& = _WIDTH(image&): deep& = _HEIGHT(image&) DIM Array(wide& * deep&) AS INTEGER _SOURCE image& 'REQUIRED to GET the proper image area! GET (0, 0)-(wide& - 1, deep& - 1), Array(0) _DEST 0 _COPYPALETTE image&, 0 'necessary for custom image colors other than screen defaults PUT(10, 10), Array(0), PSET , _RGB(255, 255, 255) 'mask white background color END
- Explanation: QB64 allows one PUT color to be "masked" to allow odd shaped sprite image backgrounds to be transparent.
Example 2: Using a STRING instead of an array to store GET image data that can be PUT later. For images up to 256 colors only.
a$ = SPACE$(4 + 100) '4 byte header + 100 pixels for a 10 X 10 image SCREEN 13 LINE (0, 0)-(319, 199), 4, BF 'color 4 = CHR$(4) = ♦ LINE (40, 40)-(49, 49), 14, B 'color 14 = CHR$(14) = ♫ GET (40, 40)-(49, 49), a$ K$ = INPUT$(1) CLS PRINT a$ 'display string data. Width = CHR$(10 * 8) = "P" PUT(100, 100), a$, PSET
- Explanation: The header holds the INTEGER width and depth of the image area as 2 bytes each. Screen 13 width is multiplied by 8.
See also:
- _PUTIMAGE, _LOADIMAGE
- _MAPTRIANGLE
- GET, BSAVE, BLOAD
- SCREEN, Scancodes(Example 3)
- Creating Sprite Masks (for non-box shaped sprites)
- GET and PUT Demo
- Bitmaps
