GPR_$INQ_DISPLAY_CHARACTERISTICS GPR Calls GPR_$INQ_DISPLAY_CHARACTERISTICS
NAME
gpr_$inq_display_characteristics - returns information about the device
or the external bitmap.
FORMAT
gpr_$inq_display_characteristics (resource_type, resource_id, disp_len,
disp, disp_len_returned, status)
DESCRIPTION
This routine returns a variety of information about the nature of the
actual display device or the external bitmap if a memory resource is
specified.
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 4-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.
⊕ Any value, such as zero, if the display resource is
gpr_$memory_bitmap.
disp_len
The size of the buffer (the disp parameter described below) in bytes
provided by the calling program, which will contain the returned
display or device information in bytes. For example, if the buffer is
ten 16-bit words in length, the program gives 20 as the value of this
parameter. No checking is (or can be) done to verify that this length
is correct, so unpredictable results are obtained if the program gives
a size that is larger than the actual size of the buffer. This param-
eter allows the calling program to request that less than the full set
of characteristics be returned. It also allows the program to con-
tinue to function correctly if the list is extended in the future. To
get the size of the buffer, use the sizeof function in C and Pascal.
In FORTRAN, use the constant gpr_$disp_char_size, which has been
defined in gpr.ins.ftn, to get this value. This parameter is a 2-byte
integer.
Output Parameters
disp Returned display device characteristics in gpr_$disp_char_t format.
This data type is a record in Pascal, a structure in C, or an array
in FORTRAN.
disp_len_returned
Actual number of bytes of data returned in the disp parameter. This
is a 2-byte integer. It will always be less than or equal to the
disp_len input parameter value.
status
Completion status, in status_$t format.
NOTES
This call takes the place of gpr_$inq_disp_characteristics.
The display resource is the equivalent of the display mode used in
gpr_$inq_disp_characteristics, except that it does not specify true or
pseudo color.
Use gpr_$inq_display_characteristics to determine your node's charac-
teristics as it runs in a specified display resource. The characteris-
tics include important information such as the size of the display screen
and the number of planes. The call returns the characteristics in the
disp parameter.
On a 24-plane or 40-plane device, the n_planes and n_buffers fields of
the display characteristics vary, depending upon whether you specify true
color or pseudo color. For true color, set n_planes to 24 and n_buffers
to 1. For pseudo color, set n_planes to 8, and n_buffers to 2.
You can call gpr_$inq_display_characteristics at any time in the program.
In fact, it is good programming practice to call
gpr_$inq_display_characteristics prior to calling gpr_$initialize. By
doing so, gpr_$inq_display_characteristics will return values (such as
bitmap size and hi_plane_id) that you can use when you call
gpr_$initialize.
Calling gpr_$inq_display_characteristics after gpr_$initialize has no
effect on the current bitmap or its attributes.
gpr_$inq_display_characteristics is a purely descriptive call.
The gpr_$inq_display_characteristics call returns information reflecting
the status of the display when the call was made. Therefore, if you call
gpr_$inq_display_characteristics prior to acquiring the display, the
returned information may not accurately reflect the future state of the
window (since the window could move, change size, or be obscured.