GPR_$INQ_DISP_CHARACTERISTICS GPR Calls GPR_$INQ_DISP_CHARACTERISTICS
NAME
gpr_$inq_disp_characteristics - returns information about the nature of
the actual display or device or external bitmap.
FORMAT
gpr_$inq_disp_characteristics (op_mode, unit_or_pad, disp_len, disp,
disp_len_returned, status)
DESCRIPTION
This routine returns a variety of information about the nature of the
actual display device or external bitmap. Use
gpr_$inq_disp_characteristics to determine your node's characteristics as
it runs in a specified display mode. The characteristics include impor-
tant information such as the size of the display screen and the number of
planes. The call returns the characteristics into the display parameter.
You can call gpr_$inq_disp_characteristics at any time in the program.
In fact, it is good programming practice to call
gpr_$inq_disp_characteristics prior to calling gpr_$init. By doing so,
gpr_$inq_disp_characteristics will return values (such as bitmap size and
hi_plane_id) that you can use when you call gpr_$init. In the future, we
may extend the list of data items returned into disp as we release new
display devices with new characteristics. However, programs written to
use the existing set of characteristics will continue to operate
correctly. Note that enumerated and set fields within disp will probably
be extended in future releases; for example, we will probably add new
controller types. Therefore, a program that depends on a particular con-
troller type returned in disp may not work when run on a future node.
Input Parameters
op_mode
The op_mode (often called display mode) for the program in
gpr_$display_mode_t format. (This is a 2-byte integer.) For exam-
ple, if you specify gpr_$borrow, GPR will return information as if
the program were running in pseudo-color borrow-display mode,
regardless of the mode that you really initialized the program in.
unit_or_pad
This parameter has three possible meanings:
⊕ 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.
⊕ For gpr_$no_display this parameter is ignored.
disp_len
Size of the buffer (the disp parameter described below) in bytes pro-
vided 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 is a
2-byte integer. This parameter allows the calling program to request
that less than the full set of characteristics to be returned. It
also allows the program to continue to function correctly if the list
of returned characteristics is extended in the future. Use the sizeof
function in C and Pascal to get this value.
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 display parameter.
This is a 2-byte integer. It will always be less than or equal to
the disp_len input parameter value. Presently, the length of the
full set of characteristics is 30 16-bit words, or 60 bytes. There-
fore, 60 is the current maximum possible value for this parameter.
status
Completion status, in status_$t format.
NOTES
Calling gpr_$inq_disp_characteristics after gpr_$init has no effect on
the current bitmap or its attributes. gpr_$inq_disp_characteristics is a
purely descriptive call.
If you specify an op_mode of gpr_$direct or gpr_$direct_rgb, the call
returns the values that are legal for a direct mode program at that
instant. (Note that direct mode programs can potentially conflict with
other direct mode programs when the display is not acquired by your pro-
gram.)
gpr_$inq_disp_characteristics returns information reflecting the status
of the display when the call was made. Therefore, if you call
gpr_$inq_disp_characteristics prior to acquiring the display, the
returned information may not accurately reflect the future state of the
window (since the window could have moved, grown, or been obscured).
On a device with 24 or 40 planes, the n_planes and n_buffers fields of
the display characteristics vary, depending upon whether you specify
true-color or pseudo-color mode. For true color, n_planes will equal 24,
and n_buffers will equal 1. For pseudo color, n_planes will equal 8, and
n_buffers will equal 2.