Q(uick)BASIC Statement (Graphics): GET
Quick View
GET
A graphics statement that stores graphic images from 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: | |||||||||||
|
- 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$ = ""
See also:
Syntax
- GET [STEP](x1,y1)-[STEP](x2,y2),arrayname[(indices)]
Description/Parameter(s)
| Argument | Description |
| x1,y1,x2,y2 | Coordinates marking a rectangular area on the screen. The placeholders x1, y1, x2, and y2 are numeric expressions that are the coordinates of diagonally opposite corners of the rectangle. |
| STEP | Keyword indicating that coordinates are relative to the most recently plotted point. For example, if the last point plotted were (10,10), then the actual coordinates referred to by STEP (5,10) would be (5+10,10+10) or (15,20). If the second coordinate pair in a GET statement has a STEP argument, it is relative to the first coordinate pair in the statement. |
| arrayname | Name assigned to the array that holds the image. This array can be of any numeric type; its dimensions must be large enough to hold the entire image. |
| indices | Numeric constants or variables indicating the element of the array where the saved image starts. |
The GET statement transfers a screen image into the array specified by arrayname. The PUT statement, associated with GET, transfers the image stored in the array onto the screen.
The following formula gives the required size of the array in bytes:
| 4 + INT(((x2 - x1 + 1) | * (bits-per-pixel-per-plane) + 7)/8) |
| * planes * ((y2 - y1) + 1) |
The bits-per-pixel-per-plane and planes values depend on the specification set in the SCREEN statement. The table below shows the number of bits per pixel per plane and the number of planes for each screen mode.
Values for Bits per Pixel per Plane and for Planes
| Screen Mode | Bits per Pixel per Plane | Planes | |
| 1 | 2 | 1 | |
| 2 | 1 | 1 | |
| 7 | 1 | 4 | |
| 8 | 1 | 4 | |
| 9 | 1 | 2 | (if 64K of EGA memory) |
| 4 | (if > 64K of EGA memory) | ||
| 10 | 1 | 2 | |
| 11 | 1 | 1 | |
| 12 | 1 | 4 | |
| 13 | 8 | 1 | |
| The bytes per element of an array are as follows: |
|
For example, suppose you wanted to use the GET statement to store an image in high resolution (SCREEN 2). If the coordinates of the upper- left corner of the image are (0,0), and the coordinates of the lower- right corner are (32,32), then the required size of the array in bytes is 4 + INT((33 * 1 + 7)/8) * 1 * (33), or 169. This means an integer array with 85 elements would be large enough to hold the image.
Unless the array type is integer or long, the contents of an array after a GET appear meaningless when inspected directly. Examining or manipulating noninteger arrays containing graphics images may cause run-time errors.
One of the most useful things that can be done with GET and PUT is animation.
Example
See the programming example for ⮜ BSAVE ⮞.
See also:
Syntax
- GET [STEP](x1!,y1!)-[STEP](x2!,y2!),arrayname[(indexes%)]
Description/Parameter(s)
- STEP makes the specified coordinates relative to the most recent point. For example, if the last point plotted were (10,10), then the actual coordinates referred to by STEP (5,10) would be (5+10,10+10) or (15,20). If the second coordinate pair in a GET statement has a STEP argument, it is relative to the first coordinate pair.
- (x1!,y1!)-(x2!,y2!) specify the screen coordinates of opposite corners of the rectangular image to store.
- The argument arrayname is the name assigned to the array that holds the image. This array can be of any numeric type; its dimensions must be large enough to hold the entire image.
- The arguments indexes% are numeric expressions indicating the element of the array where the saved image starts.
Usage Notes
- The GET statement transfers a screen image into the array specified by arrayname. The PUT statement, associated with GET, transfers the image stored in the array onto the screen.
- The following formula gives the required size of the array in bytes:
- 4+INT(((x2-x1+1)*(bits-per-pixel-per-plane)+7)/8)*planes*((y2-y1)+1)
- The bits-per-pixel-per-plane and planes values depend on the screen mode set by the SCREEN statement.
| Screen Mode | Bits per Pixel per Plane | Planes | |
| 1 | 2 | 1 | |
| 2 | 1 | 1 | |
| 7 | 1 | 4 | |
| 8 | 1 | 4 | |
| 9 | 1 | 2 | (if 64K of EGA memory) |
| 4 | (if > 64K of EGA memory) | ||
| 10 | 1 | 2 | |
| 11 | 1 | 1 | |
| 12 | 1 | 4 | |
| 13 | 8 | 1 | |
- The bytes per element of an array are as follows:
- Two bytes for an integer array element.
- Four bytes for a long-integer array element.
- Four bytes for a single-precision array element.
- Eight bytes for a double-precision array element.
- Eight bytes for a currency array element.
- For example, suppose you wanted to use the GET statement to store an image in high resolution (SCREEN 2). If the coordinates of the upper- left corner of the image are (0,0), and the coordinates of the lower- right corner are (32,32), then the required size of the array is:
- 4 + INT((33 * 1 + 7)/8) * 1 * (33), or 169 bytes.
- This means an integer array with 85 elements would be large enough to hold the image.
- Unless the array type is integer or long, the contents of an array after a GET operation appear meaningless when inspected directly. Examining or manipulating noninteger arrays that contain graphics images can cause run-time errors.
- GET and PUT statements operating on the same image should be executed in matching screen modes. This can be either the same screen mode or any screen modes with the same values for planes and bits-per-pixel-per-plane.
- One of the most useful things that can be done with GET and PUT statements is animation. See help for the PUT statement for information about how PUT arguments can be used to display a stored image with special effects such as animation.
Example
This example draws a magenta cube inside a white box and then uses the BSAVE statement to store the drawing in the file MAGCUBE.GRH. The ⮜ BLOAD statement example ⮞ program shows how you can retrieve and display the drawing.
DIM Cube(1 TO 675)
SCREEN 1
'Draw a white box.
LINE (140, 25)-(140 + 100, 125), 3, B
'Draw the outline of a magenta cube inside the box.
DRAW "C2 BM140,50 M+50,-25 M+50,25 M-50,25"
DRAW "M-50,-25 M+0,50 M+50,25 M+50,-25 M+0,-50 BM190,75 M+0,50"
'Save the drawing in the array Cube.
GET (140, 25)-(240, 125), Cube
'Set segment to the array Cube's segment and store the drawing
'in the file MAGCUBE.GRH. Note: 2700 is the number of bytes
'in Cube (4 bytes per array element * 675).
DEF SEG = VARSEG(Cube(1))
BSAVE "MAGCUBE.GRH", VARPTR(Cube(1)), 2700
DEF SEG 'Restore default BASIC segment.