The graPHIGS API is a powerful set of device-independent programming tools that allows you to design and code graphics applications that take advantage of high-function graphics devices. This chapter reviews how to access these programming tools.
The graPHIGS API is divided into two distinct parts: the graPHIGS API shell and the graPHIGS API nucleus. The graPHIGS API shell is tightly coupled to your application and does the syntax checking and building of the graphics datastream. The graPHIGS API nucleus, on the other hand, may be tightly coupled to your application also, or may run separately. The nucleus manages resources such as the structure store and the workstations. You will learn more about the relationship of the graPHIGS API shell and nucleus in the second part of this manual.
As shown in the previous sample program, to access the graPHIGS API subroutines, your application must "open" the system.
After issuing the Open graPHIGS (GPOPPH) subroutine call, all the graPHIGS API subroutines are available to your application. This subroutine also makes various stored information, maintained in internal description tables and state lists, available to your application. Due to the centralized storage for graphics data, your application can create and modify graphics data at this point without needing to open a workstation.
At the time your application issues the Open graPHIGS subroutine, a graPHIGS API shell is created. By default, the graPHIGS API will also perform the following functions:
Default creation of a nucleus and structure store is provided so that applications written for Version 1 of the graPHIGS API will continue to run without modification. The default processing of the nucleus and structure store can be changed through an External Defaults File (EDF), or through the second parameter of the GPOPPH subroutine.
In the sample program, the statement:
CALL GPOPPH('SYSPRINT',0)
opened the system and defined the environment explained above. Through this subroutine call you can also define the name of a file that will be used by the graPHIGS API as an error log. In the sample program we are naming this file 'SYSPRINT' This file will help with debugging the application.
For more information concerning the use of external defaults files and the use of the second parameter of the GPOPPH subroutine, refer to the The graPHIGS Programming Interface: Technical Reference , SC33-8193.
To display a picture that is generated from your application's graphics data, a workstation must be open. Workstations are resources owned by the nucleus. When your application issues the Create Workstation (GPCRWS) subroutine, it opens a workstation in a graPHIGS API nucleus and attaches it to a graPHIGS API shell. The following activities also take place:
In the sample program, the statement:
CALL GPCRWS(WSID,1,7,'IBM5080','5080 ',0)
opens a 5080 type workstation and establishes a connection between the workstation and the sample program. The workstation is given the workstation identifier WSID , which is used later in the program to identify the workstation.
When a workstation is opened the graPHIGS API creates and initializes an Actual Workstation Description Table (WDT) based on the workstation type parameter of the Create Workstation (GPCRWS) subroutine and the actual capabilities of the workstation. The graPHIGS API also creates a generic WDT which describes the capabilities of a generic workstation of the specified type.
An example of the values inserted into the actual WDT that may differ from the generic WDT include:
To make your application device independent, you must access the actual WDT to determine the characteristics and capabilities of the workstation your application is using. To do this, first open the workstation, then determine the name of the actual WDT by using the Inquire Realized Connection and Type (GPQRCT) subroutine. Then use the workstation type parameter returned by GPQRCT to inquire the actual workstation capabilities. Inquiry subroutines are discussed in more detail in subsequent chapters.
The close subroutines enable your application to end its use of a particular workstation, the system, or both.
In the sample program the following two statements closed the workstation and the system:
CALL GPCLWS(WSID)
CALL GPCLPH
When your application issues the Close Workstation (GPCLWS) subroutine, the graPHIGS API disconnects the target workstation and releases memory and other resources allocated for the workstation. GPCLWS also clears the input queue of any events from the given workstation.
When your application issues the Close graPHIGS (GPCLPH) subroutine, each resource, such as an open workstation, is closed. GPCLPH also invokes a set of routines that close the system. This frees all of the state lists, description tables, and associated system resources.