GPR_$INITIALIZE GPR Calls GPR_$INITIALIZE
NAME
gpr_$initialize - initializes GPR.
FORMAT
gpr_$initialize (resource_type, resource_id, options, size, pix_format,
proj_format, video_format, init_bitmap, status)
DESCRIPTION
This routine initializes the graphics primitives package, allocates and
sets an initial bitmap, and sets the pixel format, projection format, and
video format.
Input Parameters
resource_type
The display resource type, in gpr_$resource_type_t format. Possible
values for this parameter are
gpr_$memory_bitmap
A main memory bitmap. This has no effect on the screen.
gpr_$pad_id
A display-manager window
gpr_$pad_frame_id
A display-manager frame
gpr_$screen
The entire screen
gpr_$x_window_id
An X Window
resource_id
The resource identifier. This is a 4-byte integer. This value can
have the following meanings:
⊕ The display unit, if the display resource type is gpr_$screen.
This is a 2-byte integer. Currently, the only valid display
ID for gpr_$screen is 1.
⊕ The stream identifier for the pad or X window, if the display
resource is gpr_$pad_id or gpr_$x_window_id. Use stream_$id_t
format. This is a 2-byte integer.
⊕ The rectangle ID, if the display resource is gpr_$rm_id. The
rectangle ID can only be accessed internally.
options
The intialization options, in gpr_$init_options_set_t format. This is
a predefined set of gpr_$init_options_t type in Pascal. C and FOR-
TRAN do not support set types, but you can simulate this type by
declaring a long int variable in C or an INTEGER*4 in FORTRAN. This
set has 32 members. You can only use the initialization option
gpr_$no_clear, which specifies not to clear the screen. This may be
used in conjunction with a display resource type of gpr_$screen. Set
this to a null value unless you want the gpr_$noclear option.
Input/Output Parameters
size The size of the initial bitmap (or the size of the frame, if the
resource type is gpr_$pad_frame_id) in gpr_$offset_t format.
pix_format
The pixel format, in gpr_$pixel_format_t format. This data type is
a record in Pascal, a structure in C, or an array in FORTRAN. The
pixel format describes the configuration of the planes of a pixel.
proj_format
The projection format for the initial bitmap, in gpr_$proj_format_t
format. This data type is a record in Pascal, a structure in C, or
an array in FORTRAN. The projection format specifies which set of
planes will compose the initial bitmap.
video_format
The video format, in gpr_$video_format_t format. This data type is
a record in Pascal, a structure in C, or an array in FORTRAN. The
video format specifies which buffer will be displayed.
Output Parameters
init_bitmap
The descriptor of the initial bitmap, in gpr_$bitmap_desc_t format.
This is a 4-byte integer that uniquely identifies the bitmap. If
the resource type is gpr_$pad_id, gpr_$pad_frame_id, gpr_$screen_id,
or gpr_$x_window_id, the bitmap will be a display bitmap. This bit-
map consists of the group of planes specified in the projection for-
mat.
status
Completion status, in status_$t format.
NOTES
This call takes the place of gpr_$init in an application program. Pro-
grams may continue to use gpr_$init, but only if they do not require
access to the capabilities made available through gpr_$initialize.
The display resource is the equivalent of the display mode used in
gpr_$init, except that it does not specify true color or pseudo color.
If the display resource is gpr_$screen, 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 at the top
left corner of the screen.
If the display resource is gpr_$pad_id or gpr_$x_window_id, you must set
both dimensions of size to integers between 1 and 8192 inclusive. If you
provide dimensions larger than the current display window, the system
sets the size of the bitmap equal to the current size of the display win-
dow. However, if you grow the display window, the bitmap will also grow,
but cannot grow past the dimensions you specified. The origin is at the
top left corner of the display window.
If the display resource is gpr_$pad_frame_id, you must set both dimen-
sions of size to integers between 1 and 32767 inclusive. For this
display resource, size specifies the size of both the frame and the ini-
tial bitmap.
If the display resource is gpr_$memory_bitmap, you must set both dimen-
sions of size to integers between 1 and 8192 inclusive. The size that
the system allocates will equal the size that you specify.
It is not necessary to set all of the members of the pixel format record.
At a minimum, you must set the pixel_mode, the pixel_depth, and length to
2, and GPR will fill in the rest of fields for you.
The default projection format is the first buffer image planes. To get
the default projection, set proj_format.length to 0.
The default video format is the first buffer. To get the default video
format, set video_format.length to 0.
To find out what pixel formats your device supports, call
gpr_$inq_pixel_formats. The formats returned in gpr_$inq_pixel_formats
specify the maximum allowable depth of each projection for each of the
given formats. In addition, you may specify a format with fewer planes
for a particular projection than a format returned in
gpr_$inq_pixel_formats. For example, you may specify a pseudo color
pixel format with an image depth of four planes even though eight would
be available to you.
To find out the characteristics of your device to use in your initializa-
tion, call gpr_$inq_display_characteristics.
If your program uses multiple windows, you must call gpr_$initialize for
each window that uses GPR calls.
This routine initializes GPR, so that you can use the GPR routines. The
only GPR calls you can make before gpr_$initialize are
gpr_$inq_pixel_formats and gpr_$inq_display_characteristics.
For main memory bitmaps, there is no need to set the projection and video
formats. Just specify a length of 0 for each.
For main memory bitmaps, the only fields of the pixel format that need to
be set are the pixel mode, image depth, and red, green and blue depths
for true color.