GCLEAR - GSTORE

GCLEAR

Supported On UX WS DOS IN
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GCLEAR clears the graphics display or sends a command to an external plotter to advance the paper. With bit-mapped displays, the memory is cleared and the alpha is restored.

Example Statements

GCLEAR

Syntax

Multi-Plane Bit-Mapped Displays

The GCLEAR statement clears all planes designated as graphics planes with the current graphics write-mask. This includes any planes which are both alpha and graphics planes. See the "Multi-Plane Bit-Mapped Displays" section in the HP BASIC Programming Guide manual for information on enabling and displaying specific frame buffer planes.

NOTE
If any planes in the frame buffer are enabled by both the alpha mask and the graphics mask, the common planes, as well as the graphics planes, will be cleared. Then, the alpha data will be redisplayed in the common planes. This may cause text which was previously hidden or over-written by graphics to reappear.

GERMAN

See LEXICAL ORDER IS.

GESCAPE

Supported On UX WS DOS
Option Required GRAPHX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GESCAPE is used for communicating device-dependent graphics information. The type, size, and shape of the arrays must be appropriate for the requested operation.

Example Statements

GESCAPE Dev_select,operation
GESCAPE Dev_select,operation,array_in(*)
GESCAPE Dev_select,operation;array_out(*)
GESCAPE Dev_select,operation,array_in(*);array_out(*)
GESCAPE 604,10 ! HP BASIC/UX in X only

 

Syntax

Item Description Range
device selector numeric expression, rounded to an integer (see Glossary)
operation selector numeric expression, rounded to an integer (device dependent, see Semantics)
parameter array name name of array which has a specific rank and size, containing parameters necessary for executing request any valid name
return array name name of array which has a specific rank and size into which the returned parameters are placed any valid name

Semantics

Use the parameter array and return array to send data to the device and receive data from the device.

NOTE
Operation selector 1 will accept either a REAL or an INTEGER array as its return or parameter array. All other operation selectors that require parameter or return arrays will accept only INTEGER arrays.

Color Map Information

The number of entries in the color map can be determined with a GESCAPE operation selector of 1. The return array must be one-dimensional with at least one element. If this operation selector is used on a system with a monochrome display (or an HP 98627A) , error 733 will be reported.

The RGB values of the pens in the color map can be obtained through GESCAPE operation selector 2. The return array must be a two-dimensional three-column array with at least one row. The values returned are in the range of 0 to 1 and are multiples of 1/255 (one two-hundred fifty fifth) for color displays. The exception to this is the HP Model 236C computer, for which the values returned are in the range of 0 to 1 and are multiples of 1/15 (one fifteenth). The first row in the array always contains the values for PEN 0; if you want PEN 12, you must have at least thirteen rows in the array. Array filling occurs until either the array or the color map is exhausted.

The color map affects the entire display. Thus in a windowing environment, the color map is the same for all windows.

Determining Hard Clip Limits and GSTORE Array Size

The hard clip limits of the current plotting device can be obtained by executing a GESCAPE with operation selector 3. The return array must be a one-dimensional INTEGER array with at least four elements. Values will be returned in the smallest resolvable units for that device. For a CRT, the units are pixels.

Operation selector 3 also returns information useful for GSTORE and GLOAD files. The fifth and sixth elements returned give the two array dimensions to use (in conjunction with the ALLOCATE statement) to GSTORE the contents of the specified display. For example, on a HP 98544A display with all planes enabled for graphics, the dimensions returned would be 256 and 400--256 words for each of the 400 lines. That is, 1024 pixels wide, and four pixels' worth of information in each 16-bit word. This allows you to programmatically determine the size of the integer array to allocate for storing an image and thus avoid hardware-dependent code.

In HP BASIC/UX, all displays are stored as 2 pixels/16-bit word (except for monochrome, which are 16 pixels/16-bit word).

Drawing Mode Dominance

The normal drawing mode and the alternate drawing mode can be entered by using GESCAPE operation selectors 4 and 5, respectively.

For this discussion, the color of the area formed by the intersection of a newly plotted item and an existing item is the color X. In the normal drawing mode, X is the same color as the pen used to draw the newly plotted items. This is the color most recently set by PEN (for lines) or AREA (for area filling). Drawing in alternate mode with positive pen numbers causes the color-map entry number at each pixel to be inclusively-ORed with the pen value currently being drawn with. Drawing in alternate mode with negative pen numbers causes the color-map entry number at each pixel to be exclusively-ORed with the pen value currently being used to draw.

Drawing mode dominance affects the entire display. Thus in a windowing environment, all windows have the same drawing mode.

The Write Enable and Display-Enable Masks

lf you have a multi-plane frame buffer and display, there are two user-definable masks which control certain aspects of graphical operations. They are:

NOTE
Both the write-enable mask and the display-enable mask are initialized to all planes that exist in the machine at power up and SCRATCH A time.

Operation selector 6, which works with all CRTs, allows the user to obtain the current graphics write-enable and display-enable values. The first element of the return array contains the write-enable mask; the second represents the display-enable mask. The return array must be a one-dimensional integer array with at least one element. Array filling occurs until either the array or the masks are exhausted.

Operation selector 7, which works only with multi-plane Series 300 CRTs, allows the user to set the graphics write-enable and display-enable values. The first element of the parameter array contains the write-enable mask; the second represents the display-enable mask. Again, the parameter array must be a one-dimensional integer array with one or more elements. lf only one element exists, the write-enable mask is set as specified and the display-enable mask remains unchanged.

Legal values for both masks are:

The write- and display-enable masks affect the entire display. In a windowing environment, all windows are affected and have the same display mask values. The write-mask cannot be changed in X Windows, so all planes are always turned on.

Graphics Buffering (HP BASIC/UX Only)

In order to improve graphics performance, graphics buffering may be turned on with operation selector 10. Operation selector 11 will turn buffering off. This has the affect of storing graphics commands in a buffer until it is full, and then sending all of the commands in one output sequence. Because the buffer must fill up before it is sent to the display, it is possible that the output of the last few graphics commands which were executed do not appear on the display. It is advisable to flush the buffer (with operation selector 13) after each "picture" has been drawn to ensure that all the graphics commands have been sent to the display. It is NOT advisable to flush the buffer after every command, since this is the same as turning off buffering. It is also not advisable to turn buffering on while in interactive mode, since the output from any graphics commands will not appear on the display until the graphics buffer is full, or the graphics buffer is explicitly flushed. Operation selector 12 allows you to obtain the current buffering mode. The return array must be a one-dimensional integer array with at least one element.

The default graphics buffering mode may be specified in the configuration file (rmbrc). HP BASIC/UX does not support graphics buffering for HPGL plotters.

Absolute Locator Hard Clip Limits

Operation selector 20 sets the hardclip limits for absolute HP-HlL locators. That is, it simulates, in software, the changing of the hardclip limits. These limits must be inside the largest X and largest Y, taken individually, for all absolute locators on the HP-HlL bus.

Operation selector 21 returns the current hardclip limits for absolute HP-HlL locators. These are the values used in GRAPHICS INPUT IS scaling. Operation selector 21 is different than operation selector 22 in that 22 always returns the values "hardwired" into the device(s) on the HP-HIL bus, whereas the values returned by operation selector 21 may have come from operation selector 20 or from the device on the bus.

Operation selector 22 returns the hardware-defined hardclip limits of all absolute locators on the HP-HIL link.

For the three GESCAPE selectors above--20, 21, and 22--the parameter or return array must be a one dimensional integer array. Only the first two entries will be used for 20 and 21: X2 and Y2. No space is taken for the X1 and Y1 values, since the coordinates of P1 (the lower, left-hand corner) cannot be changed on HP-HIL absolute locators; X1 and Y1 will always be zeroes. For operation selector 22, entries will be made until the array is full or all devices on the bus have been covered. If more array entries exist after the devices are all represented, a -1 will be put in what would be the X coordinate entry of the next device to indicate the end of valid data. (Hardclip limits for these devices are limited to the range 0 through 32 767.)

Unlike other GESCAPES, selectors 20 through 22 do not require the device at the specified select code to be currently active. Indeed, to be effective, GESCAPE 2,20, which sets hard clip limits, must be done before doing the GRAPHICS INPUT IS KBD,"TABLET" statement. Operations 20 and 21 will give "DEVICE NOT PRESENT" errors if no tablet (or HP-HIL interface) exists, but 22 will return -1 for its first entry in that case. All will give a configuration error if the KBD binary is not present.

Functions Available Through GESCAPE
Operation\Selector Return Array (R) or Parameter Array (P)
1 (R) A(0): Number of entries in the color map
2 (R) A(0,0): Pen 0 red color map value

A(0,1): Pen 0 green color map value

A(0,2): Pen 0 blue color map value

:

A(15,0): Pen 15 red color map value

A(15,1): Pen 15 green color map value

A(15,2): Pen 15 blue color map value

3 (R) A(0): X minimum hard clip value

A(1): Y minimum hard clip value

A(2): X maximum hard clip value

A(3): Y maximum hard clip value

A(4): Rows required for GSTORE integer array

A(5): Columns required for GSTORE integer array

4 Set normal drawing mode
5 Set alternate drawing mode
6 (R) A(0): Current graphics write-enable mask value

A(1): Current graphics display-enable mask value

7 (P) A(0): Graphics write-enable mask value to be set

A(1): Graphics display-enable mask value to be set

10 Turn graphics buffering on.
11 Turn graphics buffering off.
12 (R) A(0): Current buffering mode (0 = OFF; 1 = ON)
13 Flush graphics buffer.
20 (P) A(0): X maximum hard clip value to be set

A(1): Y maximum hard clip value to be set

21 (R) A(0): Current X maximum hard clip value

A(1): Current Y maximum hard clip value

22 (R) A(0): X maximum hard clip value for first absolute locator

A(1): Y maximum hard clip value for first absolute locator

A(2): X maximum hard clip value for second absolute locator

A(3): Y maximum hard clip value for second absolute locator

:

A(n): A value of -1 indicates that there are no more absolute locators

GET

Supported On UX WS DOS IN
Option Required None
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GET reads the specified file which contains a program saved in text format, and stores the file in memory. Typically, this file is created using SAVE or RE-SAVE.

Example Statements

GET "George"
GET Progname$,Appndline,Runline 
GET "FileName:REMOTE"
GET "/Dir1/Dir2/Dir3/File SRM_READ_pass" 

Syntax

Item Description Range
file specifier string expression (see drawing)
append line number integer constant identifying a program line 1 through 32 766 (1 through 2 147 483 646| for HP BASIC/UX 700)
append line label name of a program line any valid name
run line number integer constant identifying a program line 1 through 32 766 (1 through 2 147 483 646| for HP BASIC/UX 700)
run line label name of a program line any valid name
directory path literal (see MASS STORAGE IS)
file name literal depends on volume's format (see Glossary)
SRM password literal; first 16 non-blank characters are significant > not allowed
volume specifier literal (see MASS STORAGE IS)

Semantics

The file must be an ASCII, DFS, or HP-UX file that is created using SAVE or RE-SAVE. HP-UX files must contain text written in FORMAT ON representation.

When GET is executed, the first line in the specified file is read and checked for a valid line number. If no valid line number is found, the current program stays in memory and error 68 is reported. If the GET was attempted from a running program, the program remains active and the error 68 can be trapped with ON ERROR. If there is no ON ERROR in effect, the program pauses.

If there is a valid line number at the start of the first line in the file, the GET operation proceeds. Values for all variables except those in COM are lost and the current program is deleted from the append line to the end. If no append line is specified, the entire current program is deleted.

As the file is read, each line is checked for proper syntax. The syntax checking during GET is the same as if the lines were being typed from the keyboard, and any errors that would occur during keyboard entry will also occur during GET. Any lines which contain syntax errors are listed on the PRINTER IS device. Those erroneous lines which have valid line numbers are converted into comments and syntax is checked again. lf the GET encounters a line longer than 256 characters, the operation is terminated and error 128 is reported. lf any line caused any other syntax error, an error 68 is reported at the completion of the GET operation. This error is not trappable because the old program was deleted and the new one is not running yet.

If you create long program lines on a wide display and SAVE the program, then GET the program using a narrower display, GET may produce errors and convert the long lines to comments. This happens because GET can handle program lines of up to only twice the width of the current screen or X-Window. A commented line still contains all of the original text, but any part beyond two screenwidths is invisible, leaving the line intractable in that window. For this reason, you should limit line lengths to 160 characters or less whenever possible.

Any line in the main program or any subprogram may be used for the append location. If an append line number is specified, the lines from the file are renumbered by adding an offset to their line numbers. This offset is the difference between the append line number and the first line number in the file. This operation preserves the line-number intervals that exist in the file. When a line containing an error (or an invalid line number caused by renumbering) is printed on the PRINTER IS device, the line number shown is the one the line had in the file. Any programmed references to line numbers that would be renumbered by REN are also renumbered by GET. If no append line is specified, the lines from the file are entered without renumbering.

If a successful GET is executed from a program, execution resumes automatically after a prerun initialization. If no run line is specified, execution resumes at the lowest-numbered line in the program. If a run line is specified, execution resumes at the specified line. The specified run line must be a line in the main program segment.

If a successful GET is executed from the keyboard and a run line is specified, a prerun is performed and program execution begins automatically at the specified line. If GET is executed from the keyboard with no run line specified, RUN must be executed to start the program. GET is not allowed from the keyboard while a program is running.

If you are using a version of HP BASIC| that supports wildcards, you can use them in file specifiers with GET. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details. Wildcard file specifiers used with GET must match one, and only one, file name.

HFS Permissions

In order to GET a file on an HFS volume, you need to have R (read) permission on the file, as well as X (search) permission on the immediately superior directory and all other superior directories.

SRM Files (not supported in HP BASIC/UX 700)

In order to GET a file on an SRM volume, you need to have READ capability on the file and its immediately superior directory, as well as READ capabilities on all other superior directories. If this capability is not public or if a password protecting this capability is not given, an error is reported.

You may use GET with any ASCII, DFS, or HP-UX file whose data is in the format of a HP BASIC| program (that is, having numbered lines). Although you may also use GET with ASCII files created on non-Series 200/300 SRM workstations (HP 9835, HP 9845, or Model 520), any line that is not valid HP BASIC| syntax for Series 200/300 computers is stored as a commented ( ! ) program line.

When used on SRM, GET is executed in shared mode, which means that several users can get one file at the same time. Attempts to get a locked file (see LOCK) result in Error 453. Additionally, you cannot get a file while it is being saved. The SAVE and RE-SAVE operations open the file in exclusive mode (shown as LOCK in a CAT listing) and enforce that status until the SAVE or RE-SAVE is complete. While in exclusive mode, the file is accessible only to the SRM workstation executing the SAVE or RE-SAVE.

GFONT IS

Supported On UX WS
Option Required LANGUAGE and GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GFONT IS specifies the file containing graphics fonts accessed by LABEL. It is useful in localized versions of HP BASIC| that support certain languages, such as Japanese.

Example Statements

GFONT IS "JPN_VECTOR"
GFONT IS "JPN_V*"

Syntax

Semantics

Certain localized versions of HP BASIC|, such as Japanese localized HP BASIC|, require special files containing graphics fonts to display the characters used by LABEL. You do not need to use GFONT IS unless you use these special fonts. If you do need these special fonts, you must specify their location with GFONT IS before using LABEL. If you close the GFONT file, the default font defined in the GRAPH binary is used.

For a general discussion of globalization and localization including graphics fonts, refer to the &port; manual. For details concerning a particular font, refer to Using LanguageX with HP BASIC, where LanguageX is your local language.

If you are using a version of HP BASIC| that supports wildcards, you can use them in file specifiers with GFONT IS. You must first enable wildcard recognition using WILDCARDS. Refer to the keyword entry for WILDCARDS for details. Wildcard file specifiers used with GFONT IS must match one and only one file name.

If the file specifier does not include a complete path or volume specifier, the current MASS STORAGE IS volume and path are used.

GINIT

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GINIT establishes a set of default values for system variables affecting graphics operations.

Example Statements

GINIT

Syntax

Semantics

The following operations are performed when GINIT is executed:


AREA PEN 1  
CLIP OFF  
CSIZE 5,0.6  
LDIR 0  
LINE TYPE 1,5  
LORG 1  
MOVE 0,0  
PDIR 0  
PEN 1  
PIVOT 0  
GESCAPE CRT,4                    PEN MODE NORMAL
VIEWPORT 0,RATIO*100,0,100
WINDOW 0,RATIO*100,0,100

ln addition, an active plotter or graphics input device is terminated. lf the plotter is a file, the file is closed. After a GlNlT and before a PLOTTER lS statement is executed, the following statements select a default plotter:

AXES IDRAW RECTANGLE
DRAW IMOVE RPLOT
DUMP GRAPHICS IPLOT SET ECHO
FRAME LABEL SET PEN
GCLEAR MOVE SYMBOL
GLOAD PLOT
GRID POLYGON
GSTORE POLYLlNE

GLOAD

Supported On UX* WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GLOAD loads the contents of an INTEGER array into the graphics frame buffer.

Example Statements

GLOAD Picture(*)
IF Flag THEN GLOAD Array(*)
GLOAD 28,Hp98627(*)

Syntax

Item Description Range
destination

device selector

numeric expression, rounded to an integer; Default = last CRT plotter (see Glossary)
integer array name name of an INTEGER array. any valid name

Semantics

A frame buffer is an area of memory which contains the digital representation of a raster image. A monochromatic image has a frame buffer one bit deep. The Model 236 color display has a four-bit frame buffer which allows sixteen colors. The HP 98627A external color interface has a three-bit frame buffer which allows eight colors. The HP 98543A and HP 98545A display boards have 4 planes, allowing 16 colors, and the HP 98700 has 4 or 8 planes, allowing 16 or 256 colors, respectively. The HP 98547A and HP 98549A display boards have 6 planes, allowing 64 colors. The HP 98550A and HP 98720 display boards have 8 planes, allowing 256 colors. The HP Model 362/382 internal display interfaces have 8 planes, allowing 256 colors.

If a destination device is not explicitly specified, the array's contents are loaded into the current PLOTTER IS device (if it is a frame buffer) or into the last frame buffer device specified by a PLOTTER IS statement.

GLOAD operates on active plotting devices. A plotting device is active when it is specified in a PLOTTER lS statement. ln addition, the internal CRT is also activated by any of the following operations: any pen movement; GCLEAR; GLOAD to the current default destination; GSTORE from the current default source; DUMP GRAPHlCS from the current default source; and SET PEN. Plotters are de-activated by power-up, GlNlT, SCRATCH A or [RESET].

The array's contents are loaded into the specified frame buffer if a currently active frame buffer (CRT) is explicitly specified as the destination. However, if the specified frame buffer is not activated, error 708 occurs.

The GLOAD is not performed if a non-frame buffer destination which is the current PLOTTER IS device is explicitly specified. However, if a non-frame buffer destination which is not the current PLOTTER lS device is specified, error 708 occurs.

Pixel Representation

A pixel is a picture element. Each pixel on a monochromatic display is represented by one bit in memory; a binary 1 represents a pixel that is on, while a binary 0 represents a pixel which is off. Each INTEGER array element represents 16 pixels on a monochromatic display.

Pixels on color and gray scale displays have different representation. The Model 236 color display requires four bits to represent each pixel. The optional color monitor (HP 98627) requires three bits to represent each pixel.

The number of pixels on the horizontal and vertical axes and the number of INTEGER array elements necessary to represent the entire display is shown in the following table for each model and display.

Model Horizontal\Size Vertical\Size HP BASIC/WS|\INTEGER\Elements HP BASIC/UX\INTEGER\Elements
1-plane systems:

216 (HP 9816) (monochromatic)

400 300 7500 n/a
220 (HP 9920) (monochromatic)
(HP 98204A) 400 300 7500 n/a
(HP 98204B) 512 390 12 480 n/a
226 (HP 9826) (monochromatic) 400 300 7500 n/a
236 (HP 9836) (monochromatic) 512 390 12 480 n/a
98546 (monochromatic) 512 390 12 480 12 480
237 (HP 9837) (bit-mapped, monochromatic) 1024 768 49 152 49 152
98542 (medium-resolution bit-mapped, monochromatic) 1024 400 25 600 12 800
98544 (high-resolution, bit-mapped, monochromatic) 1024 768 49 152 49 152
98548 (high-resolution, bit-mapped, monochromatic) 1280 1024 163 840 81 920
3-plane systems:

98627A (external color)

512 512 49 152 n/a
4-plane systems:

236 (HP 9836C) (color)

512 390 49 920 n/a
98543 (medium-resolution, bit-mapped, color) 1024 400 102 400 102 400
98545 (high-resolution, bit-mapped, color) 1024 768 196 608 393 216
6-plane systems:

98547 (high-resolution, bit-mapped, color)

1024 768 393 216 393 216
98549 (high-resolution, bit-mapped, color) 1024 768 393 216 393 216
8-plane systems: 98700 (high-resolution, bit-mapped, color) 1024 768 393 216 393 216
98550A (high-resolution, bit-mapped, color) 1280 1024 655 360 655 360
98720A 1280 1024 655 360 655 360
362/382 (color or gray scale) 640 480 153 600 153 600
1024 768 393 216 393 216
1280 1024 655 360 655 360

The declared array size can be larger or smaller than the graphics memory size; the operation stops when either graphics memory or the array is exhausted.

Since any one dimension of an array cannot be more than 32 767 elements, for an array to be large enough to hold the entire graphics representation, the array may have to be multi-dimensional. For example,


INTEGER Screen(1:390,1:64,1:2)    for Model 236 Color
INTEGER Screen(1:512,1:32,1:3)    for HP 98627A Color

Storage Format

The pixel representation on a monochromatic display is stored sequentially in the array using GSTORE.

The pixel representation for color displays is stored in different formats using GSTORE.

Model 236 color display: Consecutive pairs of 16-bit words are used, regardless of the array structure. P in the diagram is the 4-bit representation of the pixel.

Word 1 Word2
P5 P1 P6 P2 P7 P3 P8 P4

HP 98627A color display: Each word contains the blue, green or red representation for 16 pixels. P in the diagram is the 1-bit color representation of the pixel.

Word Pixel Color
1 P1 P2 P3 P4 ... P16 BLUE
2 P1 P2 P3 P4 ... P16 GREEN
3 P1 P2 P3 P4 ... P16 RED
4 P17 P18 P19 P20 ... P32 BLUE
5 P17 P18 P19 P20 ... P32 GREEN
6 P17 P18 P19 P20 ... P32 RED
etc.

Storage Format on Multi-Plane Bit-Mapped Displays

GLOAD loads information from an array into the graphics planes in the frame buffer. "Graphics planes" means those planes which have been write-enabled for graphics operations via power up, SCRATCH A, or GESCAPE. You can change the graphics write mask with GESCAPE.

In the following paragraphs, reference is made to the "highest graphics plane." The "highest graphics plane" is that plane in the frame buffer whose corresponding bit in the graphics write-enable mask has the highest number. For example, the highest graphics plane with a write mask of binary 1000 is 4. Also note that although bits in a byte are numbered from 0 through 7 (right to left), planes in the frame buffer are numbered 1 through 8.

If the highest graphics plane currently enabled is 1 (or none), act like there is 1. The storage format is:

Word1 P0 P1 P2 P3 ... P15
Word2 P16 P17 P18 P19 ... P31

If the highest graphics plane currently enabled is between 2 and 4, inclusive, act like there are 4. The storage format is the same as the Model 236C format, described above.

If the highest graphics plane currently enabled is between 5 and 8, inclusive, act like there are 8. The storage format is:

Word Each bit in most/significant byte Each bit in least/significant byte
Word 1

P0

P1

Word 2

P2

P3

Images should be GLOADed on the same display and with the same write-enable mask that was used when the image was GSTOREd. If these guidelines are not observed, the GLOADed image may bear no resemblance to the GSTOREd image.

To determine the number of elements needed in an integer array to hold an image, use the GESCAPE operation selector 3.

When using graphics and alpha write masks, you may prefer not to overlap the masks; that is, have any planes which are simultaneously indicated by both masks. If planes enabled for alpha overlap those enabled for graphics, some alpha information will be stored along with the graphics information.

You can conserve space if you are using fewer than the maximum number of planes. For example, on a 98700 with eight planes, if pens 0 through 15 only are being used, the graphics write mask could be set to 15 (binary 00001111) rather than the default of 255 (binary 11111111). In this way, only half the memory would be required to GLOAD the image. You can change the graphics write mask with GESCAPE.

Non-Square Pixel Displays (HP BASIC/WS| Only)

With non-square pixel displays, GSTORE stores all pixels (e.g., all 1024×400 pixels), thus requiring over twice the amount of memory as with a Model 236C. This is to insure that any image GSTOREd appears exactly the same when GLOADed back into the frame buffer. Since alpha uses the non-square pixels as separate elements--not as pairs as in graphics--it is possible to have pixel pairs with different values in each pixel. If pixel pairs were stored, images with mixed alpha and graphics could appear blurred when reloaded.

HP BASIC/UX Specifics

Storage format for all multi-plane bit-mapped displays is byte/pixel, regardless of the number of planes or value of the graphics write mask. For example:
Word Each bit in most/significant byte Each bit in least/ significant byte
Word 1

P0

P1

Word 2

P2

P3

Storage format for monochrome (1-plane) bit-mapped displays is the same for HP BASIC/WS| and HP BASIC/UX. For example:

Word1 P0 P1 P2 P3 ... P15

When HP BASIC runs in X Windows, the number of pixels on the horizontal and vertical axes, and the number of INTEGER array elements necessary to represent the entire display can vary from the default size 640X400. You can accommodate different window sizes by dynamically setting the GLOAD array size as shown in the following example:


  INTEGER A(0:5)
 
  GESCAPE CRT,3;A(*) ! Read some display parameters
 
  ALLOCATE Screen(1:A(4),1:A(5))

  GSTORE Screen(*) ! Save frame buffer into array
  
  .
 
  .
 
  .
  
  GLOAD Screen(*) ! Load the array back

GOSUB

Supported On UX WS DOS IN
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... Yes

GOSUB transfers program execution to the subroutine at the specified line. The specified line must be in the current context. The current program line is remembered in anticipation of returning.

Example Statements

GOSUB 120
IF Numbers THEN GOSUB Process

Syntax

Item Description Range
line label name of a program line any valid name
line number integer constant identifying a program line 1 through 32 766 (1 through 2 147 483 646| for HP BASIC/UX 700)

GOTO

Supported On UX WS DOS IN
Option Required None
Keyboard Executable No
Programmable Yes
In an IF ... THEN ... Yes

GOTO transfers program execution to the specified line. The specified line must be in the current context.

Example Statements

GOTO 550
GOTO Loop_start
IF Full THEN GOTO Exit

Syntax

Item Description Range
line label name of a program line any valid name
line number integer constant identifying a program line 1 through 32 766 (1 through 2 147 483 646| for HP BASIC/UX 700)

GRAPHICS

Supported On UX* WS DOS*
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GRAPHICS turns the graphics display on or off without affecting the contents of the graphics memory.

Example Statements

GRAPHICS ON
IF Flag THEN GRAPHICS OFF

Syntax

Semantics

Multi-Plane Bit-Mapped Displays

If you do not understand the concept of write-enable masks or display-enable masks, see GCLEAR before reading the following paragraphs.

GRAPHICS ON/OFF applies only to the graphics display which also is the alpha display. For example, suppose your configuration consists of a display which has both alpha and graphics, and another display which has only graphics. In this case, there would be no way, with the GRAPHICS statement, to turn graphics on or off on the display which has graphics exclusively.

With default alpha and graphics write-masks, the GRAPHICS ON and GRAPHICS OFF statements have no effect on bit-mapped displays. If designated alpha and graphics write masks do not overlap, then the statements will enable/disable graphics planes for displaying as with non-bit-mapped systems. When the write masks overlap, planes that are used only for graphics (not alpha) are enabled/disabled. For example, if the alpha write-enable mask is binary 1110 and the graphics write-enable mask is binary 0011, GRAPHICS ON and GRAPHICS OFF would only affect plane 1. Plane 2 is not affected because it is indicated by both the alpha and graphics write-enable masks, and planes 3 and 4 are not affected because they are not indicated by the graphics write-enable mask.

NOTE
Mixing ALPHA/GRAPHICS ON/OFF with explicit definition of the display-enable mask may cause the [ALPHA] and/or [GRAPHICS] keys to have unexpected results. The reason for this is that explicit setting of the display mask is, in a manner of speaking, working "behind the back" of the operating system. Thus, you could turn off graphics by modifying the display-enable mask, and the internal variables which keep track of [ALPHA] and [GRAPHICS] key presses would not--indeed, could not--have been updated. The reason these variables cannot be updated is that you can set the display mask to a state in which "alpha on" is only partially true; some alpha planes are on, and some aren't. The same goes for graphics.

HP BASIC/UX Specifics

GRAPHICS ON/OFF has no effect in a windowing environment, since the write-masks are always set to enable all planes.

HP BASIC/DOS Specifics

GRAPHICS ON/OFF functions only on SEPARATE ALPHA mode, which is supported only for VGA and EGA displays.

GRAPHICS INPUT IS

Supported On UX* WS DOS
Option Required GRAPHX
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GRAPHICS INPUT IS defines the device to be used for subsequent DIGITIZE, READ LOCATOR, SET LOCATOR, and TRACK IS...ON/OFF statements.

Example Statements

GRAPHICS INPUT IS KBD,"KBD"
GRAPHICS INPUT IS KBD,"ARROW KEYS"
GRAPHICS INPUT IS 706,"HPGL"
GRAPHICS INPUT IS Ds,Hp$
GRAPHICS INPUT IS KBD,"TABLET"

Syntax

Item Description Range
device selector numeric expression, rounded to an integer (see Glossary)
digitizer specifier string expression (see Semantics)

Semantics

The specified device is defined to be the graphics input device for subsequent graphics input statements (DIGITIZE, READ LOCATOR, SET LOCATOR, and TRACK...IS ON). This input device becomes undefined when a power-up, [RESET], GINIT, or SCRATCH A is executed. The default input device is KBD, "KBD".

The operating system attempts to use the current VIEWPORT and WINDOW (or SHOW) parameters for both the current PLOTTER IS device and the specified GRAPHICS INPUT IS device, so that the usable areas of the input and output devices correspond in a 1-to-1 mapping. If the aspect ratios of the input and output devices are different, the input device limits are truncated to match the output device's aspect ratio.

If the VIEWPORT statement specifies an area that does not exist on the input device, error 705 will be reported.

If you specify the keyboard device selector, there are two possibilities for the digitizer specifier. To specify relative pointing devices (e.g., the cursor keys, knob, or mouse), use "KBD" or "ARROW KEYS". For a port path to the Series 500, use the string "ARROW KEYS". To specify absolute pointing devices (e.g., HP-HIL tablets or the Touchscreen), use the string "TABLET". "HPGL" must be specified if the device selector is anything other than the keyboard select code.

When doing a DIGITIZE, the relative pointing devices move the graphics cursor. Otherwise, in addition to moving the graphics cursor, they perform their normal "alpha" functions: scrolling text on the screen, and moving the alpha cursor within the keyboard entry line.

HP-HIL Absolute Locators

This statement can specify HP-HIL absolute locators, which include graphics tablets as well as the Touchscreen. As with relative locators, all devices of this type are lumped together and processed as if they were a single device. This could lead to interference if two or more of these devices were connected to the HP-HIL bus. The intent is to support one active absolute locator on the HP-HIL bus, although careful use will allow more than one. In particular, the GESCAPE values of 20, 21, and 22 allow use of the HP-HIL Touchscreen on the same bus as a Tablet, provided the stylus is removed from the Tablet when the Touchscreen is in use.

Absolute Locator Hard Clip Limits

You can set the position of P2--the upper right corner of the digitizing area--on HP-HIL tablets by using GESCAPE with operation selectors 20 through 22. This is conceptually similar to setting the P2 point with HPGL commands on HPGL tablets. See GESCAPE for further information.

HP BASIC/UX Specifics

When running in X Windows:

When running on a terminal:

GRID

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GRID draws a full grid pattern. The pen is left at the intersection of the X and Y axes.

Example Statements

GRID 10,10
GRID Xspace,Yspace,Xlocy,Ylocx,Xcount,Ycount,Major_size

Syntax

Item Description Range
x tick spacing numeric expression in current units; Default = 0, no ticks (see text)
y tick spacing numeric expression in current units; Default = 0, no ticks (see text)
y axis location numeric expression specifying the location of the y axis in x-axis units; Default = 0 --
x axis location numeric expression specifying the location of the x axis in y-axis units; Default = 0 --
x major count numeric expression, rounded to an integer, specifying the number of tick intervals between major tick marks; Default = 1 (every tick is major) 1 through 32 767
y major count numeric expression, rounded to an integer, specifying the number of tick intervals between major tick marks; Default = 1 (every tick is major) 1 through 32 767
major tick size numeric expression in graphic display units; Default = 2

Semantics

Grids are drawn with the current line type and pen number. Major tick marks are drawn as lines across the entire soft clipping area. A cross tick is drawn at the intersection of minor tick marks.

The X and Y tick spacing must not generate more than 32 768 grid marks in the clip area, or error 20 will be generated. Only the grid marks within the current clip area are drawn.

Scaling PIVOT CSIZE LDIR PDIR
Lines (generated by moves and draws) X X [4]
Polygons and rectangles X X X
Characters (generated by LABEL) X X
Axes (generated by AXES & GRID) X
Location of Labels [1] [3] [2]

1The starting point for labels drawn after lines or axes is affected by scaling.

2The starting point for labels drawn after other labels is affected by LDIR.

3The starting point for labels drawn after lines or axes is affected by PIVOT.

4RPLOT and IPLOT are affected by PDIR.

GSEND

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GSEND is used to send HPGL commands to the current PLOTTER IS device.

Example Statements

IF Hpgl_device THEN GSEND "IP;"
GSEND String$

Syntax

Item Description Range
HPGL command string string expression device-dependent

Semantics

This statement sends a string of characters to the current PLOTTER IS device, which may be a file or a plotter. The string is to contain Hewlett-Packard Graphics Language (HPGL) command(s). Note that HP BASIC| does not check the syntax of these HPGL commands.

GSEND is most useful when the PLOTTER IS device is a file (it is not possible to OUTPUT an HPGL command to the file while it is the PLOTTER IS device).

An error is reported if the current PLOTTER IS device is not an HPGL device or a file.

After GSEND sends the specified string, it will send a carriage return/line feed (as an EOL sequence). If your device does not recognize a carriage return/line feed as a terminator for an HPGL command, you must include the correct terminating sequence (normally a semicolon) as part of the HPGL command string you are sending.

Note that you cannot split HPGL commands over more than one GSEND statement, because of the carriage return/line feed sequence sent after each GSEND statement. The following example will not work because it splits the HPGL command over more than one GSEND statement. (Also, the command is not properly terminated.)

GSEND "P"

GSEND "F"

The proper way to send this HPGL command is:

GSEND "PF;"

GSTORE

Supported On UX WS DOS
Option Required GRAPH
Keyboard Executable Yes
Programmable Yes
In an IF ... THEN ... Yes

GSTORE stores the contents of the graphics frame buffer into an INTEGER array.

Example Statements

GSTORE Picture(*)
IF Final THEN GSTORE A(*)
GSTORE 28,Hp98627(*)

Syntax

Item Description Range
source device selector numeric expression, rounded to an integer; Default = last CRT plotter (see Glossary)
integer array name name of an INTEGER array any valid name

Semantics

A frame buffer is an area of memory which contains the digital representation of a raster image. A monochromatic image has a frame buffer of one bit deep. The Model 236 color display has a four-bit frame buffer which allows sixteen colors. The HP 98627A external color interface has a three-bit frame buffer which allows eight colors. The HP 98543A and HP 98545A display boards have 4 planes, allowing 16 colors, and the HP 98700 has 4 or 8 planes, allowing 16 or 256 colors, respectively. The HP 98547A and HP 98549A display boards have 6 planes, allowing 64 colors. The HP 98550A and HP 98720 displays have 8 planes, allowing 256 colors. The HP Model 362/382 internal display interfaces have 8 planes, allowing 256 colors.

If a source device is not explicitly specified, the array's contents are loaded from the current PLOTTER IS device (if it is a frame buffer) or from the last frame buffer device specified by a PLOTTER IS statement.

GSTORE operates on active plotting devices. A plotting device is active when it is specified in a PLOTTER IS statement. In addition, the internal CRT is also activated by any of the following operations: any pen movement; GCLEAR; GLOAD to the current default destination; GSTORE from the current default source; DUMP GRAPHICS from the current default source; and SET PEN. Plotters are de-activated by power-up, GINIT, SCRATCH A or [RESET].

The frame buffer's contents are loaded into the specified array if a currently active frame buffer (CRT) is explicitly specified as the source. However, if the specified frame buffer is not activated, error 708 occurs.

The GSTORE is not performed if a non-frame buffer source which is the current PLOTTER IS device is explicitly specified. However, if a non-frame buffer source which is not the current PLOTTER IS device is specified, error 708 occurs.

Pixel Representation and Storage

See the GLOAD statement for details about pixel representation and storage formats.