PUT (graphics statement)

The PUT graphics statement is used to place GET or BSAVE file images stored in the designated array.

Syntax

PUT [[[STEP]]](column, row), Array([index])[,] [[[_CLIP]]] [{PSET|PRESET|AND|OR|XOR}]][, omitcolor]

Parameters:

• 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") 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

Code by Galleon

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, _SAVEIMAGE
• _MAPTRIANGLE
• GET, BSAVE, BLOAD
• SCREEN, Scancodes
• Creating Sprite Masks
• GET and PUT Demo
• Bitmaps

---

Navigation: Main Page with Articles and Tutorials Keyword Reference - Alphabetical Keyword Reference - By usage