The graPHIGS Programming Interface: ISO PHIGS Subroutine Reference

Chapter 22. graPHIGS API Extensions and Compatibility with the ISO PHIGS Standard

You can write applications that combine GPxxxx subroutine calls and ISO PHIGS subroutine calls. All of the GPxxxx subroutines (documented in The graPHIGS Programming Interface: Subroutine Reference) are available as extensions to the ISO PHIGS library of subroutine calls. This chapter identifies some graPHIGS API extensions and discusses considerations for combining GPxxxx subroutine calls and ISO PHIGS subroutine calls.

Helpful Hints
Enumerations in ISO PHIGS subroutine calls are not necessarily the same as in GPxxxx subroutine calls. Matrixes in ISO PHIGS apply to a column vector, while GPxxxx matrixes apply to a row vector. In addition, the order in which the matrix is stored is determined by the binding. See Chapter 15. "ISO PHIGS Transformations" for a description of the storage of a transformation matrix.

Helpful Hints

Enumerations in ISO PHIGS subroutine calls are not necessarily the same as in GPxxxx subroutine calls.

Matrixes in ISO PHIGS apply to a column vector, while GPxxxx matrixes apply to a row vector. In addition, the order in which the matrix is stored is determined by the binding. See Chapter 15. "ISO PHIGS Transformations" for a description of the storage of a transformation matrix.

graPHIGS API Extensions to the ISO PHIGS Standard

Many GPxxxx subroutine calls offer features beyond the ISO PHIGS standard. These include:

ISO PHIGS PLUS functions

Advanced primitives (NURBS curves/surfaces, triangle strip, . . .)
Lighting and shading
Hidden-line/hidden-surface removal (HLHSR)
Depth cueing
Direct color.

Other features

More primitives (spheres, grids, composite fill, polyhedron edge, . . .)
Proportional/filled fonts
Conditional traversal
Image display
Integration with X-Windows
Distributed architecture for networked processing
Sharing of graphical resources between processes
Enhanced structure editing
View-based traversal.

Compatibility between graPHIGS API Extensions and the ISO PHIGS Standard

When writing an application that uses both GPxxxx subroutine calls and ISO PHIGS subroutine calls, there are several considerations you should be aware of:

The architecture

To provide for distributed processing, the graPHIGS API separates its code into the graPHIGS API shell and the graPHIGS API nucleus. For more information about the graPHIGS API shell and the graPHIGS API nucleus, see The graPHIGS Programming Interface: Understanding Concepts. Many of the considerations which are listed below are directly related to the implementation of this distributed architecture.

View specification

Two approaches are available in the area of view specification. ISO PHIGS and GPxxxx subroutines provide an approach whereby structures are posted to workstations and then traversed for display. Display traversal begins with a default view index which may change during traversal due to Set View Index structure elements. For a discussion of Set View Index processing within the graPHIGS API environment, see Appendix C of The graPHIGS Programming Interface: Understanding Concepts.

In addition, through GPxxxx subroutines, the view specification may be handled in another way. Root structures may be posted to views within workstations by using the Associate Root to View (GPARV) subroutine function. Views are then traversed in output priority order. View-based traversal allows the graPHIGS API to optimize updates by redrawing only views with changed data.

The following sections describe:

Considerations for combining the two types of subroutines, listed by type of function

Rules used by the graPHIGS API when reporting errors to an application that combines subroutine calls. See Chapter 19. "ISO PHIGS Subroutines to GPxxxx Subroutines" and Chapter 20. "GPxxxx Subroutines to ISO PHIGS Subroutines" for listings of ISO PHIGS subroutines and their GPxxxx equivalents or approximate equivalents, and vice versa.

Control Subroutines

Issuing Open Workstation

Opening a workstation with the ISO PHIGS Open Workstation subroutine results in the following differences in default values used at the workstation as compared to the defaults assumed when the workstation is opened using either GPOPWS or GPCRWS.

Table 12. Default values when opening (creating) the workstation.

	ISO PHIGS Open Workstation	graPHIGS API GPOPWS or GPCRWS
Number of line types available	4	7
Number of edge types available	4	7
Default Mapping Matrixes	Maps WC cube [0,1] x [0,1] x [0,1] to the cube in NPC space of [0,1] x [0,1] x [0,1].	Maps WC cube [-1,1] x [-1,1] x [-1,1] to the cube in NPC space of [0,1] x [0,1] x [0,1].
Workstation viewport	All of DC space.	Largest square in DC space.
View input	Active for each view.	Active only for view 0.
Annotation text character height default	0.01	The nominal annotation text character height for the open workstation.
Hatch table defaults	Hatch table indexes 1-6 are as described by the Set Interior Style Index (GPISI) subroutine ( SET INTERIOR STYLE INDEX (PHOP,,STOP,)), and the remaining indexes of the hatch table are defaulted to a hatch index value of 1.	See "Interior Facilities" in The graPHIGS Programming Interface: Technical Reference.

=3>Note:
Although visual presentation on the screen is identical, the initial values in the workstation state list are different.

Issuing Open graPHIGS

If you issue the Open graPHIGS (GPOPPH) subroutine with suppression of the nucleus and structure store creation via defaults, you must create a structure store with an id value of 1 before issuing any ISO PHIGS subroutine call that attempts to access the structure store. Otherwise the graPHIGS API generates implementation errors (-11 or -12).

Since connecting to a nucleus is not an ISO PHIGS concept, when you issue an ISO PHIGS Open PHIGS subroutine call, the graPHIGS API connects to a nucleus with an id value of 1 by default. If a program issues the Open graPHIGS (GPOPPH) subroutine with suppression of the nucleus and structure store creation via defaults, and then fails to create a nucleus with an id value of 1, the graPHIGS API generates implementation error (-202) on every ISO PHIGS subroutine call that assumes a nucleus with an id value of 1. Inquire PHIGS Facilities is an ISO PHIGS subroutine call that could generate such an error.

Asynchronous Errors

Some errors from the nucleus may not be reported during the subroutine call which forced the error. The following rules are followed when reporting such an error to an application that combines GPxxxx subroutine calls and ISO PHIGS subroutine calls. (For details on the timing of error reporting, see Appendix B of The graPHIGS Programming Interface: Understanding Concepts).

If the application has opened PHIGS with ISO PHIGS Open PHIGS, the error is returned as an ISO PHIGS error, and the subroutine name is an ISO PHIGS subroutine call.

If the application has opened PHIGS with GPOPPH, the error is returned as a GPxxxx error, and the subroutine name is a GPxxxx subroutine call.

These error logs have an asterisk after the subroutine name to alert the user that this is an error being returned asynchronously from the graPHIGS API nucleus, and as such the error reported and the subroutine name follow the above rules.

The following examples illustrate these rules:

Delete Elements Between Labels and Set Element Pointer at Label could cause asynchronous GPxxxx error 130 (LABEL IDENTIFIER CANNOT BE FOUND IN THE OPEN STRUCTURE). ISO PHIGS has two distinct errors (205 and 206) defined instead. The graPHIGS API issues error 130 if you used GPOPPH, otherwise the graPHIGS API issues the mapped ISO PHIGS error.

Initialize input device subroutine calls could cause asynchronous GPxxxx error 141 (INPUT DEVICE NOT IN CORRECT MODE). ISO PHIGS defines error 251. If you used GPOPPH, then the graPHIGS API issues GPxxxx error 141, otherwise the graPHIGS API issues ISO PHIGS error 251.

Workstation Settings

The graPHIGS API supports workstations that have hatch, polymarker, and linetype tables that you can set. The following GPxxxx subroutine calls can change default entries in these tables:

GPLTR

(Set Linetype Representation)

GPMTR

(Set Marker Type Representation)

GPHR

(Set Hatch Representation)

If an application uses the GPxxxx interface to alter these tables, then the representation that ISO PHIGS defines for a line type, marker type, or hatch value has been altered.

Note: For workstations opened by an ISO PHIGS Open Workstation subroutine call, the default representations for the line type, marker type, and hatch tables are as defined by the ISO PHIGS standard.

HLHSR

ISO PHIGS has only one HLHSR mode for a workstation, whereas the GPxxxx interface has an HLHSR mode per view. If your application uses an ISO PHIGS subroutine call to set the HLHSR mode, the graPHIGS API automatically assigns this mode to view 0. The ISO PHIGS inquiry for the HLHSR mode returns the mode for view 0. The only way to set or inquire the mode of a view other than view 0 is through GPxxxx subroutine calls.

Issuing Inquires

You must be careful when your application combines GPxxxx subroutines with ISO PHIGS inquiries. Any element placed into a structure by an ISO PHIGS subroutine may always be inquired through the GPxxxx interface as well as through ISO PHIGS. However, using ISO PHIGS inquiries to obtain data that only could have been placed in a structure or into a workstation table via a GPxxxx subroutine call, generates implementation error -606.

Implementation error -606 implies that the graPHIGS API is ignoring this function, and you should use the appropriate GPQxxx inquiry to obtain the data.

Examples of error -606 on workstation inquiries:

Inquire Polyline Representation: GPxxxx subroutine calls can set polyline representations to values unknown to ISO PHIGS. Using ISO PHIGS Inquire Polyline Representation to inquire such a polyline representation generates error -606.

Inquire Polymarker Representation: GPxxxx subroutine calls can set polymarker representations to values unknown to ISO PHIGS. Using ISO PHIGS Inquire Polymarker Representation to inquire such a polymarker representation generates error -606.

Inquire Text Representation: GPxxxx subroutine calls can set text representations to values unknown to ISO PHIGS. Using ISO PHIGS Inquire Text Representation to inquire such a text representation generates error -606.

Inquire Interior Representation: GPxxxx subroutine calls can set interior representations to values unknown to ISO PHIGS. Using ISO PHIGS Inquire Interior Representation to inquire such an interior representation generates error -606.

Inquire Edge Representation: GPxxxx subroutine calls can set edge representations to values unknown to ISO PHIGS. Using ISO PHIGS Inquire Edge Representation to inquire such an edge representation produces error -606.

Inquire Color Model set to CMY: GPxxxx subroutine calls support the CMY color model, which is unknown to ISO PHIGS. Using ISO PHIGS Inquire Color Model to inquire the color model which has been set to CMY generates error -606.

Inquire state of locator device: You may issue the Initialize Locator (GPINLC) subroutine to initialize a locator device with prompt/echo types or data record variations which are not defined in ISO PHIGS. Using ISO PHIGS subroutines to inquire the state of such a locator device generates error -606.

Inquire state of stroke device: You may issue the Initialize Stroke (GPINSK) subroutine to initialize a stroke device with prompt/echo types or data record variations which are not defined in ISO PHIGS. Using ISO PHIGS subroutines to inquire the state of such a stroke device generates error -606.

Inquire state of valuator device: You may issue the Initialize Valuator (GPINVL) subroutine to initialize a valuator device with prompt/echo types or data record variations which are not defined in ISO PHIGS. Using ISO PHIGS subroutines to inquire the state of such a valuator device generates error -606.

Inquire state of string device: You may issue the Initialize String (GPINST) subroutine to initialize a string device with prompt/echo types or data record variations which are not defined in ISO PHIGS. Using ISO PHIGS subroutines to inquire the state of such a string device generates error -606.

Examples of error -606 on structure store inquiries:

Inquire element type and size or element content generated by Attribute Source Flag Setting: You may issue the Attribute Source Flag Setting (GPASF) subroutine to generate a structure element containing 0, 1, 2, or more id/flag pairs. ISO PHIGS Set Individual ASF requires exactly one id/flag pair. Thus, if the structure element placed into the structure via GPASF contains zero or more than one id/flag pair, inquiring the type and size, or the contents of this element through ISO PHIGS generates error -606.

Inquire contents of element generated by Set Edge Flag: You may issue the Set Edge Flag (GPEF) subroutine to set the edge flag to GEOMETRY ONLY in addition to the values known to ISO PHIGS Set Edge Flag. If the structure element placed into the structure via GPEF has the edge flag indicated as GEOMETRY ONLY, then using ISO PHIGS subroutines to inquire the contents of this element generates error -606.

Inquire type and size or contents of Polygon 2/3: You may issue the Polygon 2 (GPPG2) and Polygon 3 (GPPG3) subroutines to generate structure elements with zero contours and contours with 0, 1 or 2 points. All of these are unavailable through ISO PHIGS. If the contents or the type and size of such elements are inquired via ISO PHIGS, then the graPHIGS API generates error -606.

Note:

An element type may be known to both ISO PHIGS and the GPxxxx interface, but the GPxxxx interface may only know the data within the type. If such an element is inquired through ISO PHIGS, then the graPHIGS API generates error -606.

Additional information, for FORTRAN Binding Only:

Inquire element type and size or content set by Insert Application Data: Application data generated by the Insert Application Data (GPINAD) subroutine may appear to have more data when inquired by the Inquire Element Content (PQECO), the Inquire Current Element Content (PQCECO), the Inquire Element Type and Size (PQETS), or the Inquire Current Element Type and Size (PQCETS) subroutine. The length of ISO PHIGS application data is in multiples of 80 bytes. The equivalent GPxxxx subroutine call, Insert Application Data (GPINAD) specifies the exact length of application data. The GPxxxx data length is rounded up to the nearest multiple of 80 when the element is set by GPINAD and then inquired by an ISO PHIGS FORTRAN subroutine.

Inquire workstation connection and type: The connection identifier (integer) returned by the ISO PHIGS FORTRAN Inquire Workstation Connection and Type (PQWKC) subroutine is unique to ISO PHIGS. If you opened your workstation using Open Workstation (GPOPWS) or Create Workstation (GPCRWS), then the connection identifier returned by PQWKC is not usable as the connection identifier for the ISO PHIGS FORTRAN Open Workstation (POPWK) ( ). If you opened your workstation using the ISO PHIGS Open Workstation (POPWK) subroutine, then PQWKC returns the connection identifier used on that subroutine call.

Display Subroutines

The following table lists display-related ISO PHIGS calls and their equivalent GPxxxx subroutine calls:

Table 13. Display-related ISO PHIGS subroutines and their equivalent GPxxxx subroutines.

ISO PHIGS Subroutine	Equivalent GPxxxx Subroutine
Post Structure	GPARV (Associate Root with View) with a view parameter of 0
Unpost Structure	GPDRW (Disassociate Root from Workstation)
Unpost All Structures	GPDARW (Disassociate All Roots from Workstation)
Inquire Posted Structures	GPQRV (Inquire Set of Roots in View) with a requested view of 0

Input Events

For programs that combine GPxxxx subroutines and ISO PHIGS subroutines, the ISO PHIGS Await Event subroutine could return such events as Link Switch In, Link Switch Out, Update Completion, Input Overflow Events, Broadcast Message, Private Message, and Threshold Exceeded. For more information on events supported by the graPHIGS API, see The graPHIGS Programming Interface: Technical Reference.