Q(uick)BASIC Statement (Graphics): PUT

Quick View

PUT

A graphics statement that places a graphic image obtained by a GET statement onto the screen

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

GET [STEP](x1!,y1!)-[STEP](x2!,y2!), arrayname[(index%)]
PUT [STEP] (x1!,y1!), arrayname[(index%)] [,actionverb]

Description/Parameter(s)

STEP

Specifies that coordinates are relative to the current graphics cursor position.

(x1!,y1!)

The upper-left coordinates of the image captured by GET or of the screen location where PUT displays the image.

(x2!,y2!)

The lower-right coordinates of the captured image.

arrayname

The name of the array where the image is stored. See "Screen Image Arrays and Compatibility" below to determine the required size of the array.

index%

The array index at which storage of the image begins.

actionverb

A keyword indicating how the image is displayed:

Keyword	Action
AND	Merges stored image with an existing image.
OR	Superimposes stored image on existing image.
PSET	Draws stored image, erasing existing image.
PRESET	Draws stored image in reverse colors, erasing existing image.
XOR	Draws a stored image or erases a previously drawn image while preserving the background, producing animation effects.

A PUT statement should always be executed in the same screen mode as the GET statement used to capture the image, or a compatible mode:

Screen Image Arrays and Compatibility

Use bits-per-pixel-per-plane and planes values to determine the required size of the array that holds a graphics screen image. Bits-per-pixel-per-plane and planes values, along with the horizontal resolution, also determine which screen modes are compatibile:

Screen mode	Bits-per-pixel-per-plane	Planes	Horizontal resolution (in pixels)
1	2	1	320
2, 4, 11	1	1	640
3	1	1	720
7	1	4	320
8, 9 (> 64K video memory), 12	1	4	640
9 (64K video memory), 10	1	2	640
13	8	1	320

The following formula gives the required size, in bytes, of an array used to hold a captured image:

size% =	4 + INT(((PMAP (x2!, 0) - PMAP (x1!, 0) + 1) *
	(bits-per-pixel-per-plane%) + 7) / 8) * planes% *
	(PMAP (y2!, 1) - PMAP (y1!, 1) + 1)

GET and PUT operations are compatible in screen modes with the same horizontal resolution and bits-per-pixel-per-plane and planes values. For example, screen modes 2, 4, and 11 are compatible, and screen modes 8 and 12 are compatible.

Example

'This example requires a color graphics adapter.
SCREEN 1
DIM Box%(1 TO 200)
x1% = 0: x2% = 10: y1% = 0: y2% = 10
LINE (x1%, y1%)-(x2%, y2%), 2, BF
GET (x1%, y1%)-(x2%, y2%), Box%
DO
    PUT (x1%, y1%), Box%, XOR
    x1% = RND * 300
    y1% = RND * 180
    PUT (x1%, y1%), Box%
LOOP WHILE INKEY$ = ""

Syntax

PUT [STEP](x, y),arrayname[(indices)][,actionverb]

Description/Parameter(s)

Argument	Description
STEP	Indicates that the given x and y coordinates are relative, not absolute. The coordinates are treated as distances from the most recent cursor location, not distances from the (0,0) screen coordinate.
	For example, if the most recent point referenced were (10,10) then
	PUT STEP (10,5),Ball
	would put the object stored in Ball at (20,15).
(x,y)	Coordinates specifying the top-left corner of the rectangle enclosing the image to be placed in the current output window.
arrayname	The name of the array that holds the image. See the entry for GET (Graphics) for the formula that computes the size of this array. The array can be a multidimensional array.
indices	Specifies that the image is retrieved starting from the designated array element, rather than at the first array element.
actionverb	The actionverb determines the interaction between the stored image and the one already on the screen.

The different values for actionverb are described in the following list. The default actionverb is XOR.

Verb	Description
PSET	Transfers the data point-by-point onto the screen. Each point has the exact color attribute it had when it was taken from the screen with GET.
PRESET	The same as PSET except that a negative image (for example, black on white) is produced.
AND	Used when the image is to be transferred over an existing image on the screen. The resulting image is the result of a logical AND of the stored image and the screen; points that had the same color in both the existing image and the stored image remain the same color, while those points that do not have the same color in both the existing image and the stored image do not.
OR	Used to superimpose the image onto an existing image; the stored image does not erase the previous screen contents. The resulting image is the product of a logical OR of the stored image and the screen image.
XOR	A special mode often used for animation. XOR causes the points on the screen to be inverted where a point exists in the array image. This behavior is exactly like that of the cursor: when an image is placed on the screen against a complex background twice, the background is restored. This allows you to move an object around the screen without erasing the background.

Example

This example creates a moving white ball that ricochets off the sides of the screen until you press a key.

DEFINT A-Z
DIM Ball(84)     'Dimension integer array large enough
                 'to hold ball.
SCREEN 2         '640 pixels by 200 pixels screen resolution.

INPUT "Press any key to end; press <ENTER> to start", Test$
CLS
CIRCLE (16, 16), 14       'Draw and paint ball.
PAINT (16, 16), 1
GET (0, 0)-(32, 32), Ball
X = 0 : Y = 0
Xdelta = 2 : Ydelta = 1

DO
   'Continue moving in same direction as long as ball is within
   'the boundaries of the screen - (0,0) to (640,200).
   X = X + Xdelta : Y = Y + Ydelta
   IF INKEY$ <> "" THEN END  ' Test for key press.
   'Change X direction if ball hits left or right edge.
   IF (X < 1 OR X > 600) THEN
      Xdelta = -Xdelta
      BEEP
   END IF
   'Change Y direction if ball hits top or bottom edge.
   IF (Y < 1 OR Y > 160) THEN
      Ydelta = -Ydelta
      BEEP
   END IF
   'Put new image on screen, simultaneously erasing old image.
   PUT (X, Y), Ball, PSET
LOOP
END

Syntax

PUT [STEP](x!,y!),arrayname#[(indexes%)] [,actionverb]

Description/Parameter(s)

STEP indicates that the given x and y coordinates are relative, not absolute. The coordinates are treated as distances from the most- recent cursor location, not distances from the (0,0) screen coordinate. For example, if the most-recent cursor location were (10,10), then
- PUT STEP(10, 5), Ball
would put the object stored in Ball at (20,15).
(x!,y!) are coordinates that specify the top-left corner of the rectangle enclosing the image to be placed in the current output window. The entire rectangle to be put on the screen must be within the bounds of the current viewport.
Note: If a WINDOW statement without a SCREEN argument appears in a program before PUT, the coordinates refer to the lower-left corner of the rectangle.
arrayname# is the name of the array that holds the image. See the GET statement for information about the number of elements that are required in the array, which can be multidimensional.
indexes% specifies that the image is retrieved starting from the designated array element, rather than at the first array element.
The argument actionverb determines the interaction between the stored image and the one already on the screen. The default actionverb value is XOR.

actionverb	Description
XOR	Inverts the points on the screen where a point exists in the array image:
XOR	When an image is placed on the screen against a complex background twice, the background is restored; this behavior is exactly like that of the cursor. You can move an object around the screen without erasing the background, thus creating animation effects.
PSET	Transfers the data point-by-point onto the screen. Each point has the exact color attribute it had when it was taken from the screen with GET.
PRESET	The same as PSET except that a negative image (for example, black on white) is produced.
AND	Used when the image is to be transferred over an existing image on the screen:
AND	The resulting image is the result of a logical AND operation on of the stored image and the screen. Points that had the same color in both the existing image and the stored image remain the same color. Points that do not have the same color in both the existing image and the stored image do not.
OR	Used to superimpose the image onto an existing image:
OR	The resulting image is the product of a logical OR operation of the stored image and the screen image. The stored image does not erase the previous SCREEN contents.

Example

This example uses the PUT statement to create a moving white ball that ricochets off the sides of the screen until you press a key.

DEFINT A-Z
DIM Ball(84)     'Dimension integer array large enough
                 'to hold ball.
SCREEN 2         '640 pixels by 200 pixels screen resolution.
 
INPUT "Press any key to end; press <ENTER> to start", Test$
CLS
CIRCLE (16, 16), 14       'Draw and paint ball.
PAINT (16, 16), 1
GET (0, 0)-(32, 32), Ball
X = 0: Y = 0
Xdelta = 2: Ydelta = 1
 
DO
   'Continue moving in same direction as long as ball is within
   'the boundaries of the screen - (0,0) to (640,200).
   X = X + Xdelta: Y = Y + Ydelta
   IF INKEY$ <> "" THEN END  ' Test for key press.
   'Change X direction if ball hits left or right edge.
   IF (X < 1 OR X > 600) THEN
      Xdelta = -Xdelta
      BEEP
   END IF
   'Change Y direction if ball hits top or bottom edge.
   IF (Y < 1 OR Y > 160) THEN
      Ydelta = -Ydelta
      BEEP
   END IF
   'Put new image on screen, simultaneously erasing old image.
   PUT (X, Y), Ball, PSET
LOOP
END