GPR_$INIT GPR Calls GPR_$INIT
NAME
gpr_$init - initializes GPR and allocates an initial bitmap.
FORMAT
gpr_$init (op_mode, unit, size, hi_plane_id, init_bitmap_desc, status)
DESCRIPTION
This routine initializes the graphics primitives package and allocates an
initial bitmap.
The gpr_$init routine performs two separate actions. First, it initial-
izes the graphics primitives package, thus allowing you to make subse-
quent GPR calls. (The only GPR routines you can call before gpr_$init
are gpr_$inq_config and gpr_$inq_disp_characteristics.) Second, GPR
allocates a bitmap, usually in display memory.
Input Parameters
op_mode
The display mode for the program in gpr_$display_mode_t format.
Possible values for this parameter are:
gpr_$borrow
pseudo-color program borrows the full screen and the keyboard
from the Display Manager and uses the display driver directly
through GPR software. The initial bitmap will be stored in
display memory.
gpr_$borrow_rgb
true-color program borrows the full screen and the keyboard
from the Display Manager and uses the display driver directly
through GPR software. The initial bitmap will be stored in
display memory.
gpr_$borrow_nc
same as gpr_$borrow except that all the pixels are not set to
zero. (The system does not clear the screen.) The initial bit-
map will be stored in display memory.
gpr_$borrow_rgb_nc
same as gpr_$borrow_rgb except that all the pixels are not set
to zero. (The system does not clear the screen.) The initial
bitmap will be stored in display memory.
gpr_$direct
pseudo-color program borrows a window from the Display Manager
instead of borrowing the whole display. The initial bitmap
will be stored in display memory.
gpr_$direct_rgb
true-color program borrows a window from the Display Manager
instead of borrowing the whole display. The initial bitmap
will be stored in display memory.
gpr_$frame
pseudo-color program executes within a frame of a Display
Manager Pad. Frame mode is not recommended because frame mode
programs run more slowly than direct mode or borrow mode pro-
grams. The initial bitmap will be stored in display memory.
gpr_$no_display
GPR allocates a bitmap in main memory. No graphics are
displayed on the screen. The initial bitmap will be stored in
main memory (not display memory) and the program can manipulate
main memory bitmaps only.
unit This parameter has three possible meanings, as follows:
⊕ The display unit, if the graphics routines are to operate in a
borrowed display. This is a 2-byte integer. Currently, the
only valid display unit number for borrow-display mode is 1.
⊕ The stream identifier for the pad, if the graphics routines
are to operate in frame or direct mode. Use stream_$id_t for-
mat. This is a 2-byte integer.
⊕ Any value, such as zero, if the graphics routines do not use
the display.
size
The size of the initial bitmap (or the size of the frame, if op_mode
equals gpr_$frame) in gpr_$offset_t format.
hi_plane_id
Identifier of the bitmap's highest plane, in gpr_$rgb_plane_t format.
This is a 2-byte integer. Valid values for display bitmaps are:
⊕ 0 For monochromatic displays.
⊕ 0 - 3 For 4-plane color displays.
⊕ 0 - 7 For 8-plane color displays in 8-plane hardware or shared
video mode.
⊕ 0 - 23 For color displays with 24 or more planes in 24-plane
hardware or shared video mode.
For main memory bitmaps, you can use any value from 0 - 31 for all
displays.
Programs running in gpr_$borrow_rgb or gpr_$direct_rgb mode should set
hi_plane_id to 23.
Output Parameters
init_bitmap_desc
Descriptor of the initial bitmap, in gpr_$bitmap_desc_t format.
This is a 4-byte integer that uniquely identifies the bitmap.
status
Completion status, in status_$t format.
SEE ALSO
Programming with Domain Graphics Primitives.
NOTES
Use the "RGB" modes for initializing true-color programs, and use the
non-RGB modes for initializing pseudo-color programs. If you specify a
RGB mode on a node other than the DN590, the system will return the
status code:
gpr_$wrong_display_hardware
If one program uses multiple windows, you must call gpr_$init for each
window that uses GPR calls.
To use an imaging format, you must initialize the program in gpr_$borrow
or gpr_$borrow_nc mode.
The range of sizes you can specify for the bitmap depends on the op_mode.
If the op_mode is one of the four borrow modes, then you must set both
dimensions of size to an integer between 1 and 8192 inclusive. If you
provide bitmap dimensions smaller than the display memory of the node you
are using, the size of the bitmap will match the dimensions you provide,
If, however, you provide dimensions larger than the size of the display
memory, the system will reduce the size of the initial bitmap to match
the size of the display memory on your node. The origin of the bitmap is
the top left corner of the screen.
If the op_mode is one of the two direct modes, then you must set both
dimensions of size to integers between 1 and 8192 inclusive. If you pro-
vide dimensions smaller than the current display window, the system sets
the size of the bitmap equal to the values you specified. If you provide
dimensions larger than the display window, the system sets the size of
the bitmap equal to the current size of the display window. However, if
you grow the display window, then the bitmap will grow also, but cannot
grow past the dimensions you specified. The origin of the bitmap is the
top left corner of the display window.
If the op_mode is gpr_$frame, you must set both dimensions of size to
integers between 1 and 32767 inclusive. For this mode, size specifies
the size of both the frame and the initial bitmap. (In frame mode, the
frame and the bitmap are the same size; see the Programming with Domain
Graphics Primitives manual.
If the op_mode is gpr_$no_display, you must set both dimensions of size
to integers between 1 and 8192 inclusive. The size that you specify will
equal the size that the system allocates for a main memory bitmap.