Chapter 1. Introduction to the graPHIGS Programming Interface

What is the graPHIGS API?

The graPHIGS API(*) is a programming interface (subroutine package) used in the development of graphics applications. The graPHIGS API is based on the International Standards Organization (ISO) standard for Programmer's Hierarchical Interactive Graphics System (PHIGS). The graPHIGS API is a powerful graphics system that supports the definition, modification, and display of hierarchically organized graphics data.

It provides graphics application developers with a significant amount of additional function beyond the CORE, GKS, and PHIGS systems. The system adds new, more powerful concepts to provide a highly interactive, three-dimensional system that enhances the design and visualization process. The ability to organize graphic primitives into hierarchical structures makes it easy to edit, modify, and transform graphic entities.

The graPHIGS API provides programmers with the capability to design and code graphics applications that take advantage of high-function graphics devices. Using over 500 high-level graphic subroutine calls, programmers can develop applications in various programming languages.

The graPHIGS API also supports applications written to the ISO PHIGS standard interface. Applications may use calls (and the syntax) from both the graPHIGS API and ISO PHIGS interfaces, enabling access to the graPHIGS API functions, thus allowing expanded capabilities to ISO PHIGS applications.

The graPHIGS API system offers a powerful set of device-independent programming tools. The graPHIGS API decides whether to use local device capabilities or to have your central processing unit do the processing for your less intelligent workstations. The API makes the identical PHIGS function available in both mainframe and workstation environments.

Suitable application areas for graPHIGS include mechanical design, robotics, electronic design, textile design, process control, simulation, and a wide range of engineering and scientific uses.

Basic Concepts and Terminology

Graphical Resources

The graPHIGS API system consists of graphical resources with subroutines to control and utilize them. Graphical resources available to your application include:

• Structure Stores - collections of graphical elements (lines, text, etc) that help to create displayable objects
• Workstations - devices used to display the objects created by structure store elements. Workstations display the objects to a raster display or to data files, such as CGM or GDF format plot files. Workstations have input devices, such as keyboards and tablets, to provide input to your application.
• Font Directories - collections of displayable characters, typically used for different languages, appearances, or special-purpose user-defined symbols.
• Image boards - data collections for displaying images.

Subroutines

Types of subroutines available to your application include:

• Control subroutines - provide the basic control functions. These allow your application to open and close the graPHIGS API and allocate, share, control, and free graphical resources.
• Structure subroutines - provide control of structures, which are groupings of graphical elements. You can create, delete and modify structures. Modifications include changes to the whole structure content (such as emptying a structure), as well as changes to the elements in the structures (such as deleting or adding a single element in a structure).
• Element subroutines - provide the basic drawing facilities. These include primitives (such as lines, text, filled areas, curves, and surfaces) and their attributes (color, size, and linetype).
• Workstation subroutines - provide control of a workstation's facilities, such as setting a color table or view table entries.
• Display subroutines - provide the controls to display structure content on a workstation.
• Input subroutines - provide control of a workstation's input devices so that users may provide input to the application. For example, a user may want to pick a displayed object, provide text from a keyboard, or provide point or stroke (multiple points) input.
• Image subroutines - define image content and controls, such as color mappings and image display.
• Inquiry subroutines - provide your application information about the capabilities, state of resources and the system.

Resources and Capabilities

A typical use of the resources and capabilities of the graPHIGS API by your application might include the following:

• Create graphical data

  This involves creating structures containing elements and attributes that define displayed objects. Objects include:

  • Figures formed by lines and filled areas (such as a robot arm created by lines in different locations and colors)
  • Text such as labels, menus of options, and status information
  • Images.
• Open and control a workstation

  This involves identifying the current workstation and setting its values, (such as the color table), to those required for your application. This includes viewing information, which controls the parts of visible graphical data and their appearance on the display.

• Define the displayed content

  This entails associating structures of graphical data with a workstation, so that the workstation can draw the objects. The display content is modified by editing structures or changing the view tables used to display the graphical data.

• Accept user input

  This allows you to provide input to the application, typically to change the displayed objects. For example, to change an object a user might pick the object, select a choice provided by the function keys, or indicate a point or position using a tablet.

The graPHIGS API resources and facilities let you create a graphics application to display objects that a user can modify interactively. Your application can run in numerous environments, and inquiry subroutines provide information that enable your application to adapt to different hardware capabilities.

Common Terms

Following is a brief summary of common terms and their definitions used repeatedly throughout this manual.

Primitives:

The graPHIGS API defines a graphic system architecture that enables you to create, modify and display graphical objects. A sequence of elements define an object, including output primitives, attributes, and transformations. Basic output primitive elements include lines, markers, polygons, and text definitions.

Attributes:

Attributes define the characteristics of an output primitive. An attribute, for example, may define the color or size of a polymarker primitive.

Structures:

Graphical primitives and attributes group together to form structures. A structure may represent the geometry of an object, as well as information regarding the appearance of that object. Elements may be inserted into, or deleted from, structures at any time, in an operation called structure editing. This editing capability minimizes the need to redefine data in order to modify it. Structures may be related in a number of ways including geometrically, hierarchically, or characteristically, according to your application needs.

Input:

The graPHIGS API supports a wide range of input devices and provides the essential tools for application interaction. Input devices operating synchronously or asynchronously, relay information to the application, which in turn responds by defining, editing, or displaying the graphical data. The graPHIGS API supports six classes of input devices. These classes represent generic physical devices that differ from one another by the type of data they return to the application. Input device classes include the following:

1. Locator
2. Stroke
3. Valuator
4. Choice
5. Pick
6. String

The graPHIGS API supports three modes of interaction that allow you to request and obtain data from a logical input device. In Request mode, your application prompts for input and then waits until the operator either enters the requested input or performs a break action which terminates interaction. In Sample mode, your application obtains the current values of the input device by explicitly sampling it. In the Event mode, an asynchronous environment is established between your application and a chosen device. In this mode, both your application and any corresponding device operate independently of each other with the help of a centralized input queue.

Operating Modes:

The graPHIGS API supports three modes of interaction (Operating Modes) that allow you to request and obtain data from a logical input device.

1=REQUEST

Your application prompts for input and then waits until the operator either enters the requested input or performs a break action which terminates interaction.

2=SAMPLE

Your application obtains the current values of the input device by explicitly sampling it.

3=EVENT

An asynchronous environment is established between your application and a chosen device. In this mode, both your application and any corresponding device operate independently of each other with the help of a centralized input queue.

Workstations:

The term "workstation" refers to an abstraction of a physical graphics device. It provides the logical interface through which your application program controls physical devices.

The graPHIGS API provides an environment that supports multiple workstations. How your application interacts with a particular workstation depends on the interactive capabilities of that workstation and the design of your application.

The graPHIGS API supports three categories of workstations: INPUT, OUTPUT, and OUTIN. The capabilities of a workstation determine its category. For example, a INPUT workstation such as a digitizer provides only input, while an OUTPUT workstation, such as a plotter, generates only output. The OUTIN workstation, on the other hand, is an interactive design station that offers the capability of providing both input and output.

Inquiry Subroutines:

Inquiry subroutines allow the application programmer to access the program data contained in state lists, description tables, or structures. They are useful for determining both error conditions and device characteristics.

States:

The system state defines whether the graPHIGS API has been activated or deactivated, using the Open graPHIGS (GPOPPH) or Close graPHIGS (GPCLPH) subroutines respectively. No other subroutine calls can be accessed until the system is "open".

The workstation state defines whether a workstation has been activated or de-activated, using the Open Workstation (GPOPPH) or Close Workstation (GPCLPH) subroutines respectively. The graPHIGS API structure display subroutines can only be used if a workstation is "open".

The structure state defines whether the graPHIGS API display structure is "open" and able to be modified, or closed and unavailable for modification. A structure is opened and closed with the Open Structure (GPOPST) and Close Structure (GPCLST) subroutines. Graphics primitives and attributes can only be created if the structure state is "open".

Getting Started

The following is a sample graPHIGS API program to display an image of a house. It is coded using the FORTRAN language to run under VM or MVS using either a 5080 or 6090 workstation.

Accompanying the program is a sample of the output it will produce, as well as an explanation of its parts. In the chapters to follow you will be asked to modify this program and add more API functions to it, in addition to creating other assorted programs. At the end you will have a complete graPHIGS API sample program. Building the program step-by-step and then compiling, loading and running it, will help you understand the graPHIGS API.

* DECLARE VARIABLES
       INTEGER*4 STATUS,CHOICE
       INTEGER*4 WSID,STRID(5),VIEW1
       REAL*4 WINDOW(4),VIEWPT(4)
       REAL*4 HOUSE(12)
       DATA WSID /1/
       DATA STRID /1,2,3,4,5/
       DATA VIEW1 /1/
       DATA WINDOW /-100.0,100.0,-100.0,100.0/
       DATA VIEWPT /0.0,1.0,0.0,1.0/ *
       DATA HOUSE/0.0,0.0,0.0,40.0,30.0,70.0,
     *           60.0,40.0,60.0,0.0,0.0,0.0/
***********************************************************************
* OPEN FUNCTIONS
       CALL GPOPPH('SYSPRINT',0)
       CALL GPCRWS(WSID,1,7,'IBM5080','5080     ',0)
***********************************************************************
* VIEW DEFINITION CALL
       GPXVR(WSID,VIEW1,14,VIEWPT)
       CALL GPXVR(WSID,VIEW1,16,WINDOW)
       CALL GPXVCH(WSID,VIEW1,1,8,2)
***********************************************************************
* DATA CREATION
       CALL GPOPST(STRID(1))
       CALL GPPL2(6,2,HOUSE)
       CALL GPCLST
************************************************************************
* DATA DISPLAY
       CALL GPASSW(WSID,1)
       CALL GPARV(WSID,VIEW1,STRID(1),1.0)
       CALL GPUPWS(WSID,2)
***********************************************************************
* INPUT FUNCTIONS
       CALL GPRQCH(WSID,1,STATUS,CHOICE)
***********************************************************************
* CLOSE FUNCTIONS
       CALL GPCLWS(WSID)
       CALL GPCLPH
       STOP
       END

The figure, "House Created by Sample Program," shows the drawing displayed when the sample program is executed. To simplify the explanation, we have divided it into several parts. Following is a description of the various parts and their functions.

1. DECLARE VARIABLES is closely related to the language you are using to code your sample program. Depending on the language, you will probably need to declare the type and initialize the different variables of your application program before using them. In this section some of the parameters of the graPHIGS API subroutines are defined, as well a the coordinates of the drawing displayed by the program.
2. OPEN FUNCTIONS enable you to access all the available graPHIGS API application subroutine calls as well as define the workstation that will display the image. The sample program defines a 5080 type workstation and assigns it an identifier (wsid) of 1, which will be used when referring back to the workstation. If you are using a 6090 type workstation, your application will automatically access it as a 5080 type workstation.

   If you are using a workstation other than a 5080 or 6090, then replace the GPCRWS statement with one of the following:

   • If you are using a GDDM type workstation, then use:

     CALL GPCRWS(WSID,1,1,'*','GDDM    ',0)

   • If you are using an AIX type workstation, use:

           CALL GPCRWS(WSID,1,1,'*','X       ',0)

3. VIEW DEFINITION CALL is the part of the program where your application defines where on the display screen the drawing will be shown (viewpt), and what portion of the image will be displayed (window). The sample program uses all of the screen for display. Also, the drawing has been defined in a coordinate system from -100.0 to 100.0 in both the X and Y directions. These coordinates define a view window in the Workstation State List (WSL). Your application also needs to activate this view, (GPXVCH), in order for its content to be displayed.
4. DATA CREATION is the section of your program that creates the drawing. Drawings, or graphical models, are created using structures, the heart of the graPHIGS API data organization. Each structure is assigned an identifier. The sample program assigns the structure an identifier (strid(1)) of 1, which is used whenever referring to the structure.
5. DATA DISPLAY routes the drawing to the appropriate workstation for display. Before displaying your drawing, a structure store must first be associated to all views on a workstation (GPASSW) After this association is done, the structure from the structure store that has your drawing (strid(1)) is then associated to view 1 (view1) on the workstation (wsid). Finally, to display your drawing, you must update the workstation (GPUPWS)
6. INPUT FUNCTIONS allow you to interact with your application program. The example program simply displays the house and waits for a function key to be pressed before proceeding.
7. CLOSE FUNCTIONS enable your application to free the workstation and other resources used while running your application, or close the graPHIGS API system upon completing your application. The last two instructions in the sample program close the workstation and the system.

For additional information and detailed coding of specific subroutine calls, refer to The graPHIGS Programming Interface: Subroutine Reference , SC33-8194.