PUT (graphics statement)

From QB64.org wiki
Jump to: navigation, search

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



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


  • 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.


  • 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

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:

Go to Keyword Reference - Alphabetical
Go to Keyword Reference - By usage
Go to Main WIKI Page